OIDC endpoints

NamoID exposes a standard OIDC provider. You discover every endpoint from the issuer's discovery document — don't hardcode paths. This page documents what that document contains and how each endpoint behaves, so you know what your library is doing under the hood.

Discovery

GET https://<issuer>/.well-known/openid-configuration

Returns the OpenID Provider metadata for that issuer. On a hosted per-environment issuer (https://<slug>.id.namoid.in or a verified custom domain), the browser authorization and logout pages are served under /oauth/*, while token, userinfo, JWKS, and revocation are advertised by discovery. A representative document:

{
  "issuer": "https://acme.id.namoid.in",
  "authorization_endpoint": "https://acme.id.namoid.in/oauth/authorize",
  "token_endpoint": "https://acme.id.namoid.in/v1/oauth/token",
  "userinfo_endpoint": "https://acme.id.namoid.in/v1/oauth/userinfo",
  "revocation_endpoint": "https://acme.id.namoid.in/v1/oauth/revoke",
  "jwks_uri": "https://acme.id.namoid.in/v1/oauth/jwks.json",
  "end_session_endpoint": "https://acme.id.namoid.in/oauth/logout",
  "scopes_supported": ["openid", "profile", "email", "phone", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "auth_time", "nonce",
                       "name", "email", "email_verified", "phone_number",
                       "phone_number_verified"]
}

Notes:

code_challenge_methods_supported advertises only S256 — plain is not offered (OAuth 2.1).
end_session_endpoint is advertised only on hosted issuers (the ones with a browser session to end).

Authorization

GET https://<issuer>/oauth/authorize

Starts the flow. Standard parameters: response_type=code, client_id, redirect_uri, scope, state, nonce, code_challenge, code_challenge_method=S256. The user authenticates at the hosted login and is redirected back to redirect_uri with code and state.

Token

POST <token_endpoint from discovery>

Exchanges an authorization code or refreshes tokens. Confidential clients authenticate with client_secret_basic or client_secret_post.

grant_type=authorization_code — with code, redirect_uri, and the PKCE code_verifier. Returns access_token, id_token, token_type, expires_in, and (with offline_access) refresh_token.
grant_type=refresh_token — with refresh_token. Returns a fresh access token and a new refresh token, invalidating the one you sent. Replaying an old refresh token revokes the whole chain (security.refresh_replay).

The token endpoint also enforces the environment guard: a test client is rejected at the live issuer and vice versa.

UserInfo

GET <userinfo_endpoint from discovery>
Authorization: Bearer <access_token>

Returns the user's claims consistent with the granted scopes (sub, and the identity claims for profile / email / phone).

JWKS

GET <jwks_uri from discovery>

The RS256 public keys used to verify ID and access tokens. Keys rotate with overlapping windows; resolve by the token header's kid rather than pinning.

Revocation

POST <revocation_endpoint from discovery>

Revokes a token (e.g. a refresh token), per RFC 7009.

End session (RP-Initiated Logout)

GET https://<issuer>/oauth/logout

Ends the hosted-login session. Parameters: id_token_hint and optional post_logout_redirect_uri. See Sessions.

The global issuer

The product API at https://api.namoid.in also exposes discovery under /v1/oauth/* for the global issuer. For customer app integrations you almost always want your per-environment issuer (<slug>.id.namoid.in), not the global one.