OIDC Reference

Complete reference for BlokSec’s OpenID Connect implementation. For a step-by-step integration guide, see the OIDC Quickstart.

Base URL

https://api.bloksec.io

All OIDC endpoints are under the /oidc path.

Discovery

GET /oidc/.well-known/openid-configuration

Returns the full OIDC discovery document with all endpoint URLs, supported scopes, grant types, and signing algorithms. Most OIDC client libraries use this endpoint for automatic configuration.

Authorization endpoint

GET /oidc/auth

Starts the authentication flow. Redirect the user’s browser to this endpoint.

Parameters

Parameter	Required	Description
client_id	Yes	Application’s Client ID (DID)
redirect_uri	Yes	Must match a registered redirect URI
response_type	Yes	code for authorization code flow
scope	Yes	Space-separated scopes (must include openid)
state	Recommended	Random value for CSRF protection
nonce	Recommended	Random value included in the ID token
prompt	No	login forces re-authentication, consent forces consent screen
code_challenge	Required for public clients	S256 PKCE challenge
code_challenge_method	Required for public clients	Must be S256

Response

On success, redirects to redirect_uri with:

• code — authorization code (valid for 10 minutes)
• state — echo of your state parameter

Token endpoint

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

Exchanges an authorization code for tokens.

Authorization code exchange

Parameter	Required	Description
grant_type	Yes	authorization_code
code	Yes	The authorization code from the callback
redirect_uri	Yes	Must match the redirect_uri from the authorization request
client_id	Yes	Application’s Client ID
client_secret	Confidential clients	Application’s client secret
code_verifier	Public clients	PKCE code verifier

Refresh token exchange

Parameter	Required	Description
grant_type	Yes	refresh_token
refresh_token	Yes	A previously issued refresh token
client_id	Yes	Application’s Client ID
client_secret	Confidential clients	Application’s client secret

Client credentials

Parameter	Required	Description
grant_type	Yes	client_credentials
client_id	Yes	Application’s Client ID
client_secret	Yes	Application’s client secret
scope	No	Requested scopes

Response

{
  "access_token": "eyJhbGci...",
  "id_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "openid email profile"
}

UserInfo endpoint

GET /oidc/userinfo
Authorization: Bearer {access_token}

Returns claims about the authenticated user based on the scopes granted.

Response

{
  "sub": "did:bloksec:abc123",
  "email": "user@example.com",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Smith",
  "name": "Jane Smith"
}

JWKS endpoint

GET /oidc/jwks

Returns the JSON Web Key Set used to sign tokens. Use these keys to verify ID token and access token signatures.

End session endpoint

GET /oidc/end_session

RP-initiated logout. Redirect the user to this endpoint to end their BlokSec session.

Parameter	Required	Description
id_token_hint	Recommended	The ID token issued to the client
post_logout_redirect_uri	No	Must match a registered post-logout redirect URI
state	No	Echoed back in the redirect

Additional endpoints

Endpoint	Method	Description
/oidc/introspect	POST	Token introspection (RFC 7662)
/oidc/revoke	POST	Token revocation (RFC 7009)

Scopes and claims

Available scopes

Scope	Claims included
openid	sub, aud, amr
email	email, email_verified
profile	given_name, family_name, name, nickname, picture, preferred_username, updated_at, account, upn, user_did
phone	phone_number, phone_number_verified
offline_access	Grants a refresh token

The openid scope is required for all requests.

Token lifetimes

Token	Lifetime
Access token	1 hour
ID token	1 hour
Authorization code	10 minutes
Refresh token	7 days
Client credentials	10 minutes

Supported grant types

Grant type	Description
authorization_code	Standard browser-based login (default)
refresh_token	Refresh an expired access token
client_credentials	Server-to-server authentication

PKCE

PKCE (Proof Key for Code Exchange) is required for public clients (where token_endpoint_auth_method is none). Only the S256 challenge method is supported.

Error responses

Token endpoint errors follow RFC 6749:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Common errors:

Error	Description
invalid_client	Client authentication failed
invalid_grant	Authorization code is invalid or expired
invalid_scope	Requested scope is not allowed
unauthorized_client	Client is not authorized for this grant type