Skip to content
Sudomimus

Dynamic registration API

View as Markdown

Use dynamic registration when an RP needs to create a client under approved organization authority. Obtain an Initial Access Token (IAT) first. Read registration_endpoint from discovery.

Register a code-flow client

Section titled “Register a code-flow client”

The following example uses client_secret_basic. The IAT must permit code, authorization_code, refresh_token, and all requested scopes. The redirect host must have an approved placement in the organization’s Sector.

Save this as registration.json:

{
  "client_name": "Example RP",
  "redirect_uris": ["https://app.example.com/oidc/callback"],
  "post_logout_redirect_uris": ["https://app.example.com/"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "application_type": "web",
  "scope": "openid email profile offline_access",
  "token_endpoint_auth_method": "client_secret_basic",
  "subject_type": "pairwise",
  "id_token_signed_response_alg": "RS256"
}

Send the JSON with a Bearer IAT from your backend:

Terminal window
curl -X POST "$REGISTRATION_ENDPOINT" \
  -H "Authorization: Bearer $IAT" \
  -H "Content-Type: application/json" \
  --data-binary @registration.json

Success returns HTTP 201. The following excerpt shows the credentials and metadata to retain; the response also includes other current registration metadata.

{
  "client_id": "example-rp",
  "registration_client_uri": "https://oidc.sudomimus.com/register/example-rp",
  "registration_access_token": "<RAT>",
  "client_secret": "<client secret>",
  "client_secret_expires_at": 0,
  "redirect_uris": ["https://app.example.com/oidc/callback"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "application_type": "web",
  "scope": "openid email profile offline_access",
  "token_endpoint_auth_method": "client_secret_basic"
}

Store the RAT and client secret as backend secrets. A client_secret_expires_at value of 0 means no scheduled expiry; rotation or revocation can still invalidate the secret. Use the returned client_id for authorization. Registration consumes one unit of the IAT’s quota and creates an active application under its selected template.

Metadata rules

Section titled “Metadata rules”
Field Rule
redirect_uris Required nonempty array. Authorization uses exact URI matching.
response_types Defaults to ["code"]. Each requested type must be permitted by the IAT.
grant_types Defaults to ["authorization_code"]. Code-bearing types require authorization_code; all other response types require implicit.
scope Space-separated supported scopes within the IAT’s allowance. If omitted, defaults to permitted scopes compatible with the grants. Must include openid; offline_access requires refresh_token.
application_type Defaults to web. Native clients use custom schemes or exact HTTP loopback URIs; HTTPS is rejected for native clients. Web Implicit/Hybrid requires HTTPS without localhost or loopback hosts.
token_endpoint_auth_method Defaults to client_secret_basic. Also supports client_secret_post, private_key_jwt, and none. Public code-bearing clients require PKCE S256.
jwks / jwks_uri Choose one RP public-key source. Required for dynamic private_key_jwt. See RP keys.
sector_identifier_uri For multiple redirect hosts, supply an HTTPS JSON array containing every exact redirect URI. Its host must be approved for the organization’s Sector.
post_logout_redirect_uris Registered exact logout destinations.
initiate_login_uri Optional HTTPS RP endpoint without a fragment for third-party login initiation.
Signing preferences id_token_signed_response_alg, userinfo_signed_response_alg, token_endpoint_auth_signing_alg, and request_object_signing_alg support RS256 where applicable. Encryption is unsupported.
Authentication preferences default_max_age, require_auth_time, default_acr_values, and request_uris. See advanced OIDC.
Presentation client_name, client_uri, policy_uri, tos_uri, logo_uri, their language-tagged forms, and contacts. Names follow the naming policy. Links use HTTPS.

Registration JSON is limited to 65,536 bytes. Lists are limited to 32 entries; public JWKS sets are limited to 16 keys. Logos must be PNG, JPEG, GIF, or WebP and at most 64 KiB each. Do not submit private JWK fields.

Read a registration

Section titled “Read a registration”

Use the returned registration_client_uri and that client’s RAT:

Terminal window
curl "$REGISTRATION_CLIENT_URI" \
  -H "Authorization: Bearer $RAT"

Success returns HTTP 200 with current metadata and the current client secret for shared-secret clients. It does not return a replacement RAT. Responses are audited and must not be cached.

The RAT does not permit metadata updates. Use With to edit rules and RP public keys. PUT registration updates are unsupported. To change an active client’s initiate_login_uri, contact Sudomimus support.

Remove a registration

Section titled “Remove a registration”
Terminal window
curl -X DELETE "$REGISTRATION_CLIENT_URI" \
  -H "Authorization: Bearer $RAT"

Success returns HTTP 204 with no body. It disables the dynamically registered application, removes its OIDC registration, and revokes the RAT. The application remains available as a retained management resource. The client cannot authorize, exchange tokens, or read that registration after removal.

Handle failure

Section titled “Handle failure”

A metadata error returns HTTP 400 with invalid_client_metadata or invalid_redirect_uri. An unusable IAT returns HTTP 401 with invalid_token. A registration read or delete with another client’s valid RAT returns HTTP 403. See OIDC troubleshooting.

A repeated POST /register can create another client and consume another quota unit. If a network failure leaves the result unknown, ask the OWNER to review registrations in With before submitting another request.

Section titled “Related”