Dynamic client registration (RFC 7591)

POST/register

Registers a new client and returns its credentials plus a registration_access_token and registration_client_uri for managing the registration via RFC 7592.

POST/register

curl -X POST 'https://auth.example.com/register' \
  -H "Authorization: Bearer $INITIAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": [
      "https://app.example.com/callback"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "response_types": [
      "code"
    ],
    "client_name": "Example App",
    "scope": "openid profile email"
  }'

Response

201 Created

{
  "client_id": "nauthera_2Rk9",
  "client_id_issued_at": 1735686000,
  "client_secret_expires_at": 0,
  "registration_client_uri": "https://auth.example.com/register/nauthera_2Rk9"
}

Authorization

Initial access token

Send it in the Authorization header:

The access token, as Bearer <token> (RFC 6750 §2.1) or, for a sender-constrained token, DPoP <token> (RFC 9449 §7.1). A token minted with a cnf.jkt confirmation is only accepted together with a DPoP proof signed by that key, whichever of the two schemes carries it.

Headers

DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's cnf.jkt and cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.

Request body

application/json

Client metadata for dynamic registration (RFC 7591 §2, with OpenID Connect Dynamic Client Registration extensions).

client_idstring
RFC 7592 §2.2 requires an UPDATE (PUT) body to carry the client's own client_id, and the server MUST reject a value that differs from the currently issued one. On registration (POST) it is ignored: a client never influences its own identifier (RFC 9700 §4.15.1).
at most 256 characters
client_secretstring
RFC 7592 §2.2: if present on an UPDATE it MUST match the currently issued secret; a client may never overwrite its secret with a value of its own choosing. Ignored on registration.
at most 512 characters
redirect_urisarray of strings · uri
Redirection URIs (REQUIRED for redirect-based grants).
Example["https://app.example.com/callback"]
1–32 items · no duplicates · each item: at most 2048 characters
token_endpoint_auth_methodenum
Possible values"none""client_secret_basic""client_secret_post""private_key_jwt""tls_client_auth""self_signed_tls_client_auth"
token_endpoint_auth_signing_algenum
Possible values"ES256""RS256"
grant_typesarray of strings
Example["authorization_code","refresh_token"]
at most 16 items · no duplicates · each item: at most 128 characters
response_typesarray of strings
Example["code"]
at most 8 items · no duplicates · each item: at most 64 characters
client_namestring
Example"Example App"
at most 256 characters
client_uristring · uri
at most 2048 characters
logo_uristring · uri
at most 2048 characters
scopestring
Example"openid profile email"
at most 2048 characters · pattern ^\S+( \S+)*$
contactsarray of strings · email
at most 32 items · no duplicates · each item: at most 256 characters
tos_uristring · uri
at most 2048 characters
policy_uristring · uri
at most 2048 characters
jwks_uristring · uri
at most 2048 characters
jwksobject
A JSON Web Key Set.
Show child attributesHide child attributes
- keysarray of objectsrequired
  A public JSON Web Key (RFC 7517). Two key types are published: EC (kty=EC, ES256/P-256) carries crv/x/y per RFC 7518 §6.2, and RSA (kty=RSA, RS256) carries n/e per RFC 7518 §6.3. The two member sets are mutually exclusive, so only kty/use/kid/alg are required — a key serializes exactly the members its own type defines.
  Show item attributesHide item attributes
  ktystringrequired
  Example"EC"
  usestringrequired
  Example"sig"
  kidstringrequired
  Example"7Xy1t-abc"
  algstringrequired
  Example"ES256"
  crvstring
  Example"P-256"
  xstring
  Example"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU"
  ystring
  Example"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  nstring
  Example"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbW"
  estring
  Example"AQAB"
software_idstring · uuid
software_versionstring
at most 128 characters
software_statementstring
at most 16384 characters
application_typeenum
Possible values"web""native"
subject_typeenum
Possible values"public""pairwise"
sector_identifier_uristring · uri
at most 2048 characters
id_token_signed_response_algstring
at most 16 characters
userinfo_signed_response_algstring
at most 16 characters
request_object_signing_algstring
at most 16 characters
default_max_ageinteger
between 0 and 315360000
require_auth_timeboolean
default_acr_valuesarray of strings
at most 16 items · no duplicates · each item: at most 256 characters
initiate_login_uristring · uri
at most 2048 characters
post_logout_redirect_urisarray of strings · uri
at most 32 items · no duplicates · each item: at most 2048 characters
backchannel_logout_uristring · uri
at most 2048 characters
backchannel_logout_session_requiredboolean
frontchannel_logout_uristring · uri
at most 2048 characters
frontchannel_logout_session_requiredboolean

Responses

201 Createdapplication/jsonThe client was registered.
The client was registered.
Headers
- Cache-Controlno-store
- Pragmano-cache
Body
Client information response (RFC 7591 §3.2.1 + RFC 7592). Echoes the registered metadata and adds the server-issued credentials and management fields.
- client_idstringrequired
  Example"nauthera_2Rk9"
- client_secretstring
  Present for confidential clients only.
- client_id_issued_atinteger
  Example1735686000
- client_secret_expires_atinteger
  Epoch seconds, or 0 if the secret never expires.
  Example0
- registration_access_tokenstring
  RFC 7592 token authorizing management of this registration.
- registration_client_uristring · uri
  RFC 7592 management endpoint for this client.
  Example"https://auth.example.com/register/nauthera_2Rk9"
- redirect_urisarray of strings · uri
- token_endpoint_auth_methodstring
- token_endpoint_auth_signing_algstring
- grant_typesarray of strings
- response_typesarray of strings
- client_namestring
- client_uristring · uri
- logo_uristring · uri
- scopestring
- contactsarray of strings
- tos_uristring · uri
- policy_uristring · uri
- jwks_uristring · uri
- software_idstring
- software_versionstring
- application_typestring
- post_logout_redirect_urisarray of strings · uri
- id_token_signed_response_algstring
- backchannel_logout_uristring · uri
- backchannel_logout_session_requiredboolean
- frontchannel_logout_uristring · uri
- frontchannel_logout_session_requiredboolean
400 Bad Requestapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"
401 Unauthorizedapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"

PreviousClient Registration NextRead a client registration

Dynamic client registration (RFC 7591)

POST/register

Initial access token Rate limited

Registers a new client and returns its credentials plus a registration_access_token and registration_client_uri for managing the registration via RFC 7592.

POST/register

curl -X POST 'https://auth.example.com/register' \
  -H "Authorization: Bearer $INITIAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uris": [
      "https://app.example.com/callback"
    ],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "response_types": [
      "code"
    ],
    "client_name": "Example App",
    "scope": "openid profile email"
  }'

Response

201 Created

{
  "client_id": "nauthera_2Rk9",
  "client_id_issued_at": 1735686000,
  "client_secret_expires_at": 0,
  "registration_client_uri": "https://auth.example.com/register/nauthera_2Rk9"
}

Authorization

Initial access token

Send it in the Authorization header:

Headers

DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's cnf.jkt and cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.

Request body

application/json

Client metadata for dynamic registration (RFC 7591 §2, with OpenID Connect Dynamic Client Registration extensions).

client_idstring
RFC 7592 §2.2 requires an UPDATE (PUT) body to carry the client's own client_id, and the server MUST reject a value that differs from the currently issued one. On registration (POST) it is ignored: a client never influences its own identifier (RFC 9700 §4.15.1).
at most 256 characters
client_secretstring
RFC 7592 §2.2: if present on an UPDATE it MUST match the currently issued secret; a client may never overwrite its secret with a value of its own choosing. Ignored on registration.
at most 512 characters
redirect_urisarray of strings · uri
Redirection URIs (REQUIRED for redirect-based grants).
Example["https://app.example.com/callback"]
1–32 items · no duplicates · each item: at most 2048 characters
token_endpoint_auth_methodenum
Possible values"none""client_secret_basic""client_secret_post""private_key_jwt""tls_client_auth""self_signed_tls_client_auth"
token_endpoint_auth_signing_algenum
Possible values"ES256""RS256"
grant_typesarray of strings
Example["authorization_code","refresh_token"]
at most 16 items · no duplicates · each item: at most 128 characters
response_typesarray of strings
Example["code"]
at most 8 items · no duplicates · each item: at most 64 characters
client_namestring
Example"Example App"
at most 256 characters
client_uristring · uri
at most 2048 characters
logo_uristring · uri
at most 2048 characters
scopestring
Example"openid profile email"
at most 2048 characters · pattern ^\S+( \S+)*$
contactsarray of strings · email
at most 32 items · no duplicates · each item: at most 256 characters
tos_uristring · uri
at most 2048 characters
policy_uristring · uri
at most 2048 characters
jwks_uristring · uri
at most 2048 characters
jwksobject
A JSON Web Key Set.
Show child attributesHide child attributes
- keysarray of objectsrequired
  A public JSON Web Key (RFC 7517). Two key types are published: EC (kty=EC, ES256/P-256) carries crv/x/y per RFC 7518 §6.2, and RSA (kty=RSA, RS256) carries n/e per RFC 7518 §6.3. The two member sets are mutually exclusive, so only kty/use/kid/alg are required — a key serializes exactly the members its own type defines.
  Show item attributesHide item attributes
  ktystringrequired
  Example"EC"
  usestringrequired
  Example"sig"
  kidstringrequired
  Example"7Xy1t-abc"
  algstringrequired
  Example"ES256"
  crvstring
  Example"P-256"
  xstring
  Example"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU"
  ystring
  Example"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  nstring
  Example"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbW"
  estring
  Example"AQAB"
software_idstring · uuid
software_versionstring
at most 128 characters
software_statementstring
at most 16384 characters
application_typeenum
Possible values"web""native"
subject_typeenum
Possible values"public""pairwise"
sector_identifier_uristring · uri
at most 2048 characters
id_token_signed_response_algstring
at most 16 characters
userinfo_signed_response_algstring
at most 16 characters
request_object_signing_algstring
at most 16 characters
default_max_ageinteger
between 0 and 315360000
require_auth_timeboolean
default_acr_valuesarray of strings
at most 16 items · no duplicates · each item: at most 256 characters
initiate_login_uristring · uri
at most 2048 characters
post_logout_redirect_urisarray of strings · uri
at most 32 items · no duplicates · each item: at most 2048 characters
backchannel_logout_uristring · uri
at most 2048 characters
backchannel_logout_session_requiredboolean
frontchannel_logout_uristring · uri
at most 2048 characters
frontchannel_logout_session_requiredboolean

Responses

201 Createdapplication/jsonThe client was registered.
The client was registered.
Headers
- Cache-Controlno-store
- Pragmano-cache
Body
Client information response (RFC 7591 §3.2.1 + RFC 7592). Echoes the registered metadata and adds the server-issued credentials and management fields.
- client_idstringrequired
  Example"nauthera_2Rk9"
- client_secretstring
  Present for confidential clients only.
- client_id_issued_atinteger
  Example1735686000
- client_secret_expires_atinteger
  Epoch seconds, or 0 if the secret never expires.
  Example0
- registration_access_tokenstring
  RFC 7592 token authorizing management of this registration.
- registration_client_uristring · uri
  RFC 7592 management endpoint for this client.
  Example"https://auth.example.com/register/nauthera_2Rk9"
- redirect_urisarray of strings · uri
- token_endpoint_auth_methodstring
- token_endpoint_auth_signing_algstring
- grant_typesarray of strings
- response_typesarray of strings
- client_namestring
- client_uristring · uri
- logo_uristring · uri
- scopestring
- contactsarray of strings
- tos_uristring · uri
- policy_uristring · uri
- jwks_uristring · uri
- software_idstring
- software_versionstring
- application_typestring
- post_logout_redirect_urisarray of strings · uri
- id_token_signed_response_algstring
- backchannel_logout_uristring · uri
- backchannel_logout_session_requiredboolean
- frontchannel_logout_uristring · uri
- frontchannel_logout_session_requiredboolean
400 Bad Requestapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"
401 Unauthorizedapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the suffix of type), so consumers can branch on it without parsing prose. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"urn:problem-type:validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values"invalid_request""invalid_credentials""forbidden""unauthorized""insufficient_user_authentication""protected_account""last_role_administrator""invalid_code""too_many_requests""too_many_attempts""account_locked""account_unavailable""already_enrolled""registration_disabled""registration_conflict""captcha_failed""invalid_reset_link""invalid_verification_link""invalid_invitation_link""mail_relay_missing""not_found""conflict""unavailable""busy""window_too_large""too_many_series""internal_error""rate_limited""malformed""body_too_large""required""validation_error""unknown_org""invalid_token""invalid_dpop_proof""use_dpop_nonce""server_error"
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/jsonRegistration error (RFC 7591 §3.2.2).
Registration error (RFC 7591 §3.2.2).
Headers
- Cache-Controlno-store
- WWW-Authenticatestring
- DPoP-Noncestring
Body
A dynamic client registration error (RFC 7591 §3.2.2).
- errorenumrequired
  Possible values"invalid_redirect_uri""invalid_client_metadata""invalid_software_statement""unapproved_software_statement""invalid_token""access_denied""temporarily_unavailable"
- error_descriptionstring
  Example"token_endpoint_auth_method is not supported"

PreviousClient Registration NextRead a client registration

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Body

Headers

Body