API reference

All NIA endpoints live under your issuer. Point any OIDC library at the discovery document and it configures the rest automatically.

Issuer:     https://dev-api.niaauth.com
Discovery:  https://dev-api.niaauth.com/.well-known/openid-configuration

Client authentication at the token/introspect/revoke endpoints:

• client_secret_basic — client_id:client_secret in the Authorization: Basic header (confidential clients).
• client_secret_post — client_id + client_secret in the form body (confidential clients).
• none — public clients send no secret and rely on PKCE.

Token, introspection and revocation requests use Content-Type: application/x-www-form-urlencoded. Access tokens are RS256 JWTs sent as Authorization: Bearer <token>.

Authorization request — redirect the user here:

https://dev-api.niaauth.com/oauth/authorize
  ?response_type=code
  &client_id=your-client-id
  &redirect_uri=https://app.example.com/auth/callback
  &scope=openid%20email%20profile
  &state=RANDOM
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256
  &nonce=RANDOM

Token exchange — swap the code for tokens:

curl -X POST https://dev-api.niaauth.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.example.com/auth/callback \
  -d client_id=your-client-id \
  -d client_secret=your-client-secret \
  -d code_verifier=CODE_VERIFIER

UserInfo — read claims for an access token:

curl https://dev-api.niaauth.com/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

The OpenID Connect discovery document advertises every endpoint and capability. Standard libraries fetch it once and configure themselves — you only ever need to give them the issuer URL.

{
  "issuer": "https://dev-api.niaauth.com",
  "authorization_endpoint": "https://dev-api.niaauth.com/oauth/authorize",
  "token_endpoint": "https://dev-api.niaauth.com/oauth/token",
  "userinfo_endpoint": "https://dev-api.niaauth.com/oauth/userinfo",
  "jwks_uri": "https://dev-api.niaauth.com/oauth/jwks.json",
  "scopes_supported": ["openid", "email", "profile", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"]
}

NIA signs ID and access tokens with RS256. The public keys are published as a JSON Web Key Set so resource servers can verify tokens offline — no call back to NIA.

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "2026-08-01",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZ...",
      "e": "AQAB"
    }
  ]
}

To verify a token:

• Read the kid from the JWT header.
• Fetch the JWKS and select the key with the matching kid.
• Verify the RS256 signature, then check iss, aud and exp.

Keys rotate periodically — cache the JWKS but refetch by kid when you see an unknown one. Your library handles this automatically. Inspect the live keys in the JWKS Viewer under Developer Tools.

NIA's OAuth endpoints are rate-limited to protect the service. If you exceed a limit you receive HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

• Cache tokens — reuse an access token until shortly before expires_in instead of requesting one per API call.
• Cache discovery & JWKS — fetch them once and refresh periodically (refetch JWKS by kid on an unknown key), not on every request.
• Respect Retry-After — back off for the indicated time on a 429 rather than retrying immediately.
• For machine-to-machine traffic, request one token and reuse it across calls — see the Machine-to-machine guide.