HTTP integration reference

This reference covers the current application-facing hosted protocol and permission-check interface. It is not a complete public Management API. Use the authenticated console for workspace, user, application, client, role, provider and API-grant administration.

Base URL and conventions

<issuer> means the exact configured issuer, including its tenant path: https://<authentication-host>/t/<tenant-id>. Discover it from the application’s integration details. Do not substitute the console origin or assume that api.oathvera.com is the base for these endpoints.

All production requests use HTTPS. Endpoint paths and identifiers are case-sensitive. OAuth request bodies are application/x-www-form-urlencoded; permission-check bodies are JSON. Duplicate or unrecognized OAuth parameters can be rejected. Do not add library defaults that are absent from the supported fields below.

Endpoint map

Method	Path relative to issuer	Purpose
GET	/.well-known/openid-configuration	Discovery metadata. Include client_id for deterministic client-specific scope metadata.
GET	/.well-known/jwks.json	Public signing keys. Cache according to response headers and refresh on legitimate key rollover.
GET	/oauth2/authorize	Start human hosted sign-in.
POST	/oauth2/token	Code exchange, rotating refresh or M2M token issuance.
GET	/oidc/userinfo	Minimal identity claims for a valid human access token with openid.
GET	/oidc/session	Current human-token/session authority without loading profile claims.
POST	/oauth2/revoke	Revoke a token or its human grant/family.
POST	/oauth2/introspect	Confidential client’s own-token activity information.
GET	/oidc/logout	Browser hosted-session logout to a registered destination.
POST	/authorization/check	Current permission decision, called by an API server.

Discovery and JWKS can resolve an active workspace client without the query parameter. An explicit client_id on discovery avoids relying on the most recently updated active client’s scope metadata. The returned issuer and endpoint addresses remain workspace/hostname-based. Metadata advertises platform grant types; the selected client’s type still restricts which grants it can use.

Authorization request

All of these fields are required:

Field	Value
client_id	Active interactive client ID.
redirect_uri	Exact registered callback.
response_type	code.
scope	Space-separated, unique scopes including openid. Only registered identity scopes and permitted resource permissions.
state	Fresh random base64url value, 24–128 characters.
nonce	Independent fresh random base64url value, 24–128 characters.
code_challenge	Base64url SHA-256 digest of the verifier, without padding.
code_challenge_method	S256.

Optional: one resource, equal to an active API audience explicitly granted to this client. Current limits permit at most 68 unique requested scopes including identity scopes. M2M clients cannot use this endpoint.

On success, the registered callback receives code, state and iss. Require a single value for each, the original state, and your configured issuer. The code is single-use and valid for 60 seconds. Unsupported parameters include prompt, max_age, login_hint, organization, connection, response_mode and audience; do not infer support from another provider’s API.

Hosted authentication can show errors within the transaction. Applications must also handle callback errors or missing required success fields without establishing a session. Never navigate to an unvalidated callback-supplied return URL.

Client authentication

Client	Token and revocation requests	Introspection
SPA / public web / native	client_id in body, no secret. Allowed browser origin required for browser calls.	Not available.
Confidential server web	HTTP Basic client credential.	Basic, own tokens only.
M2M	HTTP Basic client credential.	Basic, own tokens only.

Construct Basic as base64 of formEncode(client_id) + ':' + formEncode(client_secret). Basic authenticates the client and supplies its ID. A redundant body ID must match. Requests with body client_secret, mixed authentication methods, duplicate fields or an Origin on confidential authentication are rejected. client_secret_post, private-key JWT and mTLS authentication to Oathvera are not currently supported.

Token request fields

Grant	Required form fields	Optional fields
Authorization code	grant_type=authorization_code, code, redirect_uri, code_verifier; client_id for public clients.	Matching body client_id for Basic-authenticated clients.
Refresh	grant_type=refresh_token, refresh_token; client_id for public clients.	scope to narrow the existing grant; matching body ID with Basic.
M2M	grant_type=client_credentials, resource, scope, plus Basic authentication.	Matching body client_id.

A PKCE verifier is 43–128 characters from the RFC 7636 unreserved character set. Use 32 cryptographically random bytes encoded as base64url for a 43-character verifier. Keep it for the initiating transaction only.

Do not repeat resource in code exchange or refresh; code exchange uses the original authorization request’s resource. A narrowed refresh scope limits that access token, not the original family’s scope ceiling. M2M requires a nonempty list of at most 64 unique API permissions and rejects identity scopes. Code/refresh responses return opaque access_token, token_type: "Bearer", expires_in, scope and a replacement refresh_token; initial code exchange also returns id_token. Do not require a new ID token on refresh.

M2M returns only access token, bearer type, lifetime and scope. OAuth forms are limited to 8 KiB in this implementation. Confidential authentication is rate-limited; its current internal authentication limit can surface as an authentication failure rather than a distinct 429. Edge limits may return 429. Back off on repeated failures and investigate rather than immediately rotating a correct credential.

ID token and UserInfo

Verify ID-token ES256 signature with the issuer’s JWKS; exact issuer, client ID audience, expiry, issued-at time and transaction nonce. Use a JWT verification library, not base64 decoding. OpenID Connect’s validation model is described in OIDC Core; this table describes Oathvera’s narrower current output.

Claim	Current meaning
iss, sub, aud, iat, exp	Issuer, pairwise subject, client audience and token times.
nonce	Original authorization request nonce.
auth_time	Time of authentication.
acr, amr	Oathvera assurance context and recorded authentication methods; not third-party certification claims.
sid	Hosted session reference.
organization_id, connection_id	Present for enterprise organization sessions.

GET /oidc/userinfo with Authorization: Bearer <human-access-token> returns sub and, for enterprise sessions, the organization and connection IDs. Requested email scope releases the active identity’s email and explicit email_verified proof; profile releases an optional nonempty name. The same scoped profile claims can appear in the ID token. Historical email values without verification proof remain unverified. Avatar and arbitrary profile fields are not released. M2M has no user profile and is not accepted by UserInfo.

Online human-session check

GET /oidc/session takes Authorization: Bearer <human-access-token> and returns active: true, iss, client_id, sub and exp only when the token and its current authority remain valid. It checks the same token, grant, session, client, user/application and applicable organization/connection authority as UserInfo, without decrypting the identity profile. The token must include openid; M2M tokens are rejected.

Require HTTP 200, active === true, exact issuer/client/subject matching the local session and a future expiry. Invalid or expired authority returns 401; unresolved host/tenant/client routing can return 404, and unavailable authority returns 503. Every non-success fails closed. Responses are no-store; do not cache an affirmative result across protected requests.

This Oathvera-specific endpoint supports a server application’s current-session check. It does not replace signed ID-token validation during login, supply verified profile claims, authorize API permissions or replace the confidential-client introspection contract. Use UserInfo when profile claims are needed and /authorization/check for resource permissions.

Revocation

POST /oauth2/revoke accepts token, the public client’s client_id or Basic identity, and optional token_type_hint. A successful response has HTTP 200 with no body. Unknown tokens may also return 200. Human revocation ends the associated grant/family, not just a single access-token string. See lifecycle semantics.

Introspection

POST /oauth2/introspect requires Basic and form token; optional token_type_hint and matching body client ID. Only the authenticated client’s own token is returned as active. A valid active-token response includes active, client_id, sub, iss, aud, scope, exp and token_type; service tokens add principal_type: "workload". Otherwise the response can be { "active": false }.

Introspection does not return a user-role decision or give one client permission to inspect every other client’s token. Resource servers should use /authorization/check for action authorization.

Hosted logout

Navigate the user’s browser to /oidc/logout with exactly client_id and post_logout_redirect_uri. It requires the hosted session cookie and an active matching grant. The destination must be registered; successful logout returns a 303 redirect and clears the hosted session cookie. No id_token_hint, logout state, SAML SLO or upstream logout forwarding is implemented.

Permission check

Server-side POST /authorization/check, Bearer access token, JSON with exactly resource, permission and organization_id (an organization ID or null). Maximum body: 2 KiB. No query string or Origin header. See authorization for the full enforcement sequence and different human/workload responses.

Only HTTP 200 with allowed === true permits an operation. The API must derive the expected resource, permission and organization context from its own trusted routing/data.

Errors and recovery

Result	Integration action
400 / invalid_request	Check exact fields, duplication, encoding, allowed flow and callback. Do not retry the same malformed request.
400 / invalid_scope	Check registered scopes, resource and client API grant; do not broaden permissions automatically.
invalid_grant	Code/refresh proof or its authority is unusable; restart human sign-in instead of replaying it. M2M may also lose authority during issuance.
401 / invalid_client or authentication failure	Check client type, credential, expiry and issuer. Do not downgrade to public authentication.
403	Denied origin or access policy; verify configuration.
404 / generic invalid_request	Host/tenant/client/lifecycle resolution may have failed. A hidden or inactive object is not necessarily distinguishable from a nonexistent route.
413 / 415	Request body too large or wrong media type.
429	Stop immediate retries and back off with jitter, honoring Retry-After when present.
503 or network/parse failure	Treat identity/permission as unconfirmed and deny the protected action. Record a safe operational error.
200 with allowed: false / active: false	HTTP success is not authorization success.

Error bodies differ between the OAuth boundary and permission checks. Branch on the operation and status, then the documented fields; do not depend on one universal error envelope. Never expose raw credential/token bodies in error reporting.

Automatic retries are suitable only when their semantics are understood. Code redemption and refresh consume one-time proofs; a lost response is an ambiguous outcome. Discovery can be retried with bounds. Permission checks can be retried before an action only while continuing to deny on uncertainty. M2M retries can create more than one short-lived token; do not retry in a tight loop.

Compatibility limits

The public /v1/access/, /v1/audit/ and /v1/management/ API families are reserved and currently fail closed at the public edge. Console routes and internal service bindings are not substitutes for a released customer REST API. Do not infer a public API-key, webhook, SDK or lifecycle-delivery contract from a UI catalog entry.

This implementation uses the secure code-flow approach described in the OAuth security best current practice. Support for this selected profile does not claim OpenID certification or implementation of every standard extension.