Skip to content

Dynamic client registration

This page helps you register an app as a client by calling the auth server, rather than creating it in the admin console.

That’s dynamic client registration (DCR), POST /connect/register, as RFC 7591 defines it. It’s how tools like MCP clients get a client of their own. What a self-registered client may do once it exists is on Clients.

  1. In the admin console, turn on Dynamic client registration under Admin, General. It’s off until you do.

  2. Send the app’s metadata as JSON:

    Terminal window
    curl -X POST https://auth.example.com/connect/register \
    -H 'Content-Type: application/json' \
    -d '{
    "client_name": "My CLI tool",
    "redirect_uris": ["http://127.0.0.1/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code"]
    }'
  3. Keep the client_id from the answer. Your app signs users in with it, as any other client does:

    HTTP/1.1 201 Created
    Content-Type: application/json
    Cache-Control: no-store
    {
    "client_id": "dcr_6f1c2a9e-3b7d-4e0a-9c55-2d8b1e4f7a10",
    "client_id_issued_at": 1759900000,
    "client_secret_expires_at": 0,
    "redirect_uris": ["http://127.0.0.1/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "client_name": "My CLI tool",
    "dpop_bound_access_tokens": false
    }

The body is a JSON object. The auth server reads ten fields and ignores every other one, as RFC 7591 asks:

Field What it does
redirect_uris Where the auth server may send the browser back. Required when the client uses the authorization code flow. See redirect URIs below.
post_logout_redirect_uris Where the auth server may send the browser back after a sign-out: the client’s sign-out redirect URIs. Optional. They follow the same rules as redirect_uris, below.
token_endpoint_auth_method none makes a public client, with no secret. client_secret_basic, the default, or client_secret_post makes a confidential one, with a secret, which it must then send that way only. See Client authentication.
grant_types Any of authorization_code, the default, refresh_token and client_credentials, with at least one of authorization_code and client_credentials. A public client can’t ask for client_credentials, and the legacy flows can’t be asked for at all: the client is registered with both off, whatever the global settings under Admin, General.
client_name The name the consent screen shows, up to 100 characters, the bound of the client’s description it’s stored as, with no < or >.
policy_uri The app’s privacy policy, which the consent screen links. Kept only on one of the client’s hosts: see Privacy policy and terms of service below.
tos_uri The app’s terms of service, which the consent screen links. Kept only on one of the client’s hosts, as policy_uri is.
backchannel_logout_uri Where the auth server tells the app that a user’s session ended: the client’s back-channel logout URI. Optional. See Back-channel logout below.
backchannel_logout_session_required true when the app needs the session identifier, sid, in every logout token it’s sent. Optional, false by default, and stored only with a backchannel_logout_uri.
dpop_bound_access_tokens true when the app always uses DPoP: the client is registered to require DPoP for token requests, so a token request without a proof is refused. Optional, false by default.

refresh_token sets nothing of its own: a client with the authorization code flow gets a refresh token with every code it redeems, whether it asked for refresh_token or not.

A body larger than 64 KiB is refused as one that can’t be read.

A self-registered client’s redirect URIs follow the rules for every client, and the stricter ones on Redirect URIs for self-registered clients: a public client gets loopback http and custom schemes, a confidential one https and loopback http. On top of those, a registration holds at most 60 redirect URIs, each up to 2,048 bytes, and none listed twice.

post_logout_redirect_uris follows the same rules, for the same kind of client, and holds up to 60 entries of its own. A sign-out matches them exactly, port included, as Sign-out redirect URIs explains, and never uses redirect_uris.

A backchannel_logout_uri follows the rules for every client, and must use https, whether the client is public or confidential: http is refused, on 127.0.0.1 and localhost too. The registration must also ask for the authorization_code grant type, since a client that signs no users in has no session to end. The auth server sends logout tokens only to a public address for a self-registered client.

The consent screen links a client’s policy_uri and tos_uri, so users can read them before they allow the app in. Anyone can register a client, so the auth server keeps a URL only when it’s on the app’s own site. It keeps each one when it:

  • is an http or https URL of up to 256 characters;
  • has the same scheme and host as one of the client’s redirect_uris. The host compares without regard to case, and the port isn’t compared.

Any other value is dropped, and the client is registered without it. The answer carries only the URLs that were kept. So a client whose redirect URIs are on 127.0.0.1 or a custom scheme, as a CLI or MCP tool’s often are, can’t register a privacy policy on its website. An administrator can set both URLs on the client’s Settings tab, where they aren’t checked against the redirect URIs.

The new client is enabled straight away, and:

  • Its identifier is generated, dcr_ followed by a UUID, and can’t be changed later.
  • A confidential client gets a secret of 60 characters, which the answer carries once. A public client gets none.
  • A confidential client is held to the method it registered, as Client authentication describes.
  • Consent is on, so users see what it asks for before it gets a token.
  • A public client has Remember consent off, so users see the consent screen on every sign-in, even after they’ve approved it. A confidential client remembers it.
  • Its sign-in level is urn:goiabada:level2_optional, so a user with two-factor authentication set up is asked for their code. See ACR and AMR.
  • A public client always uses PKCE.
  • Its token lifetimes are copied from Admin, Tokens onto its own Tokens tab when it registers, so a later change to the server’s settings doesn’t reach it.

It starts with no permissions, and isn’t allowed to request the administrative scopes. In the admin console it’s marked Self-registered, and an administrator can change its settings like any other client’s once they’ve reviewed it.

There’s no endpoint to read, update or delete a registration afterwards, so the answer carries no registration_access_token. To change a self-registered client, an administrator does it in the admin console.

Each registration leaves a dynamic_client_registration entry in the audit log.

A registration is answered 201 Created, with Cache-Control: no-store, and the client’s metadata as JSON:

Field What it holds
client_id The client’s identifier, dcr_ followed by a UUID
client_secret The client’s secret, for a confidential client only. It isn’t sent again: an administrator can read it later on the client’s Authentication tab.
client_id_issued_at When the client was created, in seconds since 1970
client_secret_expires_at Always 0: the secret never expires
redirect_uris The redirect URIs, as registered
post_logout_redirect_uris The sign-out redirect URIs, as registered, when any were sent
token_endpoint_auth_method The method, with the default filled in
grant_types The grant types the client can use, whatever the request listed: authorization_code and refresh_token for a client with the authorization code flow, and client_credentials for one with that grant
response_types Always sent: ["code"] for a client with the authorization code flow, and [] for one without it, whatever the request listed
client_name The name, when one was sent
policy_uri The privacy policy URL, when one was sent and kept
tos_uri The terms of service URL, when one was sent and kept
backchannel_logout_uri The back-channel logout URI, when one was sent
backchannel_logout_session_required Whether every logout token names the session, true or false, beside a backchannel_logout_uri
dpop_bound_access_tokens Whether the client requires DPoP for token requests, true or false, always

An error is answered with a JSON body holding error and error_description, as RFC 7591 section 3.2.2 defines:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_redirect_uri",
"error_description": "redirect_uris required for authorization_code grant type"
}
error Status Why
access_denied 403 DCR is off: “Dynamic client registration is not enabled”
invalid_client_metadata 400 The body isn’t JSON or is too large, or a field holds a value the auth server doesn’t take: an unknown token_endpoint_auth_method, a grant type it doesn’t take, implicit and password included, client_credentials on a public client, grant_types with neither authorization_code nor client_credentials, a client_name too long or holding < or >, a sign-out redirect URI that’s malformed, refused for this kind of client, too long, listed twice, or one too many, a back-channel logout URI the auth server can’t use, or a backchannel_logout_session_required or dpop_bound_access_tokens that isn’t true or false
invalid_redirect_uri 400 A redirect URI is missing, malformed, refused for this kind of client, too long, listed twice, or one too many
server_error 500 The auth server couldn’t save the client. Nothing was registered.

The error_description says which value was refused, so it’s worth showing to whoever is setting the app up.

With the rate limiter on, an IP address past its budget is answered 429 Too Many Requests with invalid_request, “Too many requests. Please wait and try again later.”

While DCR is on, the discovery document carries registration_endpoint, the URL of /connect/register. While it’s off, the field isn’t there, so an app can tell from discovery whether it may register.