OpenID Connect endpoints

Each realm is an OpenID Provider of its own. Its issuer is {base}/realms/{realm} and every endpoint sits under it, so a client configured with the issuer finds the rest through discovery. The examples on this page use the realm acme on the shared platform:

https://authio.api.hyperio.tech/realms/acme

On a Dedicated environment, replace the host with your environment’s API address. A token issued by one realm is never accepted by another.

Endpoints at a glance

Limits count each caller per realm. A refused request gets 429 with a Retry-After header. Responses that carry credentials — token, introspection, revocation, UserInfo, device authorization — are sent with Cache-Control: no-store.

Discovery

The provider metadata is served at three addresses, so a client finds it whichever convention it follows: OpenID Connect Discovery appends the suffix to the issuer, while RFC 8414 inserts it after the host, the form MCP clients try first.

curl https://authio.api.hyperio.tech/realms/acme/.well-known/openid-configuration
curl https://authio.api.hyperio.tech/.well-known/oauth-authorization-server/realms/acme
curl https://authio.api.hyperio.tech/.well-known/openid-configuration/realms/acme

The document describes the realm as it is configured, not a generic catalogue:

There is no dynamic client registration endpoint, and signed request objects (request, request_uri) are not supported. Discovery answers 404 for a realm that does not exist.

JWKS

The public keys that verify the realm’s tokens, as a JWK Set (RFC 7517). Every token names the key that signed it in its kid header. Keys rotate on a schedule, so cache the set and fetch it again when a token names a kid you do not have.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/certs

Authorization endpoint

Starts a sign-in with the authorization code flow. The browser is sent here, the hosted login runs the client’s sign-in steps, and the browser comes back to your redirect_uri with a code.

https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/auth
  ?client_id=acme-web
  &response_type=code
  &redirect_uri=https%3A%2F%2Fapp.acme.com%2Fcallback
  &scope=openid%20profile%20email%20offline_access
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

The response carries code, state and iss (RFC 9207). The code is valid for 30 seconds and only once: presenting it again revokes the session it was issued in. Until the redirect_uri is proven, errors are shown on an error page rather than redirected; after that they come back to the redirect_uri with error, error_description, state and iss.

Token endpoint

Exchanges a grant for tokens. The body is application/x-www-form-urlencoded. A confidential client authenticates with HTTP Basic (client_secret_basic, the default) or with client_id and client_secret in the body (client_secret_post) — only the method registered on the client is accepted, and Basic wins when both are sent. A public client sends only its client_id and relies on PKCE. Private key JWT client authentication is not supported.

Supported grants

Each grant must be enabled on the client. An unknown grant gets unsupported_grant_type; a known one the client has not enabled gets unauthorized_client.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/token \
  -u "acme-web:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  --data-urlencode redirect_uri=https://app.acme.com/callback \
  -d code_verifier="$CODE_VERIFIER"

Device authorization

Starts the device flow (RFC 8628) for input-constrained devices. The client authenticates as at the token endpoint and must have the device code grant enabled.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/device/auth \
  -d client_id=acme-cli \
  --data-urlencode "scope=openid profile offline_access"

While the person decides, polling answers authorization_pending; polling too fast answers slow_down; after 10 minutes, expired_token; a denied request, access_denied. See Device flow.

UserInfo

Returns the current claims of the person behind an access token: always sub, plus the claims the token’s profile, email and phone scopes allow, read fresh on every call. A token without openid gets 403 with insufficient_scope; an invalid one, 401 with invalid_token, both with a WWW-Authenticate header.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Introspection

Tells an API whether a token is still active (RFC 7662), including revocation, ended sessions and suspended users that a signature check alone cannot see. The caller authenticates as a client. The answer is always 200: {"active": false} for any token that is not valid, with no reason given.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/introspect \
  -u "acme-web:$CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN" \
  -d token_type_hint=access_token

An active token returns active, scope, client_id, username, token_type, exp, iat, nbf, sub, aud, iss and jti, plus authorization claims such as roles, acr, amr, sid and the organization. With token_type_hint=api_key the client asks about one of its consumers’ API keys instead: an active key returns sub (the consumer), client_id, scope, consumer_name, credential_id, credential_type and consumer_resource_access.

Revocation

Invalidates a token you no longer need (RFC 7009), typically at sign-out. The caller authenticates as a client, and every well-formed request gets 200, even for an unknown or expired token. Revoking ends the session behind the token, which also invalidates its refresh tokens; the person stays signed in to the realm’s other applications.

curl https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/revoke \
  -u "acme-web:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" \
  -d token_type_hint=refresh_token

End session

Signs the person out of the realm (RP-Initiated Logout). Send the browser here with:

https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/logout
  ?id_token_hint=ID_TOKEN
  &post_logout_redirect_uri=https%3A%2F%2Fapp.acme.com%2F
  &state=af0ifjsldkj

Clients that registered a back-channel or front-channel logout URI are told whenever one of their sessions ends — at sign-out, but also when an administrator revokes it or the user is suspended. See Sessions and SSO.

Other addresses under a realm

Errors

Protocol endpoints answer errors with the fields of RFC 6749 §5.2, plus Authio’s own error_code to match a report against the logs:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials. The provided client_secret is not valid.",
  "error_code": "InvalidClientCredentials"
}

Every error value and the codes behind it are listed in Error codes.

Next steps