# Dynamic client registration

Let client applications register themselves via OAuth 2.0 Dynamic Client Registration, using initial access tokens.

> **Note:** Available with the Advanced and Pro subscription. Open registration for AI agents requires Pro.

With **dynamic client registration**, a client application registers itself instead of being created by hand in the Admin Console. It sends its metadata (name, redirect URIs, client authentication) to the registration endpoint and receives a client ID and, for confidential clients, a client secret in return. The platform implements OAuth 2.0 Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) and the management protocol that lets the client read, update and delete its own registration later ([RFC 7592](https://www.rfc-editor.org/rfc/rfc7592)).

By default, every registration needs an **initial access token** that you issue, so you decide who may register clients and how often. For AI agents and other public clients you can additionally allow [open registration](#open-registration-for-ai-agents).

You manage initial access tokens under **Integrations → Applications → Dynamic registrations** in the Admin Console.

## How it works

1. You issue an **initial access token** and hand it to the party that registers the client, for example a partner or a deployment pipeline.
2. The client sends a registration request to the registration endpoint, with the initial access token as Bearer token.
3. The platform checks the metadata against the rules below, creates the application and answers with the client credentials plus a **registration access token** and the client's own management URL.
4. With the registration access token, the client can read, update or delete its registration. Every update issues a new registration access token and invalidates the previous one.

The registered client is listed on the **Dynamic registrations** tab under **Registered applications**, together with how it registered and when it was last used. Its detail page is the same as for any other application, marked **Dynamically registered**. Nobody can sign in to it yet: as with every new application, access has to be [assigned](https://dts-identity.com/docs/integrations/applications.md#assigning-applications-to-users) first.

## Issuing an initial access token

1. Go to **Integrations → Applications** and open the **Dynamic registrations** tab.
2. Select **Issue token**.
3. Enter a **Name**, for example the partner or system the token is for. It appears in the list and in the audit log.
4. Set the **Validity in days** (1 to 365). The token expires after this period.
5. Leave **Single use** selected if the token should allow exactly one registration. Clear it to allow any number of registrations until the token expires.
6. Select **Issue token** and copy the token. It is shown only once and cannot be retrieved later.

The page also shows the **Registration endpoint** to pass on together with the token. It is published as `registration_endpoint` in the OpenID Connect discovery document as well.

The list shows each token's usage, the number of registrations made with it, its expiry and who issued it. **Revoke** stops a token from being used for new registrations. Applications already registered with it stay unaffected. Expired tokens are removed automatically.

## Open registration for AI agents

> **Note:** Available with the Pro subscription.

AI agents, for example clients of the Model Context Protocol (MCP), and command-line tools register themselves the moment a user connects them, without anyone handing out a token. Each installation typically registers its own client. Open registration allows exactly that for **public clients**, which have no client secret and sign users in with the authorization code flow and PKCE.

1. Go to **Settings → Advanced**.
2. In the **Open registration** card, switch on **Open registration for public clients**.
3. Under **Users who may sign in**, select the directories whose users may use such clients.
4. Select **Save changes**.

For openly registered clients:

- **Only public clients are accepted.** A registration without an initial access token must send `"token_endpoint_auth_method": "none"`, and the client stays public: a later update cannot add a client secret. Confidential clients still need an initial access token.
- **Access comes from the directories.** Users of the selected directories may sign in after giving consent, without an assignment per application. The selection applies to new registrations; applications already registered keep the directories they were registered with.
- **Registrations are rate limited** to 10 per hour per client IP address and 200 per hour in total (20 during the trial).
- **Unused registrations are removed.** A client nobody signed in to is deleted after 24 hours, a client without sign-ins or token requests for 90 days as well. Each removal is recorded in the audit log.
- **There is no owner.** Openly registered applications are not assigned to an administrator.

The registration endpoint is announced in the discovery document, which is served at `/.well-known/openid-configuration` and, for OAuth clients that look for it there, at `/.well-known/oauth-authorization-server`. If an agent requests an access token for a specific resource, such as an MCP server, register that resource as an [API](https://dts-identity.com/docs/integrations/apis.md).

Switching open registration off stops new anonymous registrations. Clients already registered keep working and can still manage their registration. Without the Pro subscription, users of the directories no longer get access to openly registered clients automatically: assign them explicitly, otherwise the unused clients are removed after 90 days.

## Registering a client

The client sends its metadata as a JSON `POST` request:

```bash
curl -X POST https://id.example.com/oidc/register \
  -H "Authorization: Bearer <initial access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Partner Portal",
    "redirect_uris": ["https://portal.partner.example/callback"],
    "post_logout_redirect_uris": ["https://portal.partner.example/"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'
```

A successful registration answers with `201 Created`:

```json
{
  "client_id": "V1StGXR8_Z5jdHi6B-myT",
  "client_secret": "...",
  "client_name": "Partner Portal",
  "redirect_uris": ["https://portal.partner.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
  "registration_access_token": "..."
}
```

The client stores `client_secret` and `registration_access_token` securely. Neither can be retrieved again.

## Managing the registration

The client manages its registration at `registration_client_uri`, authenticated with its current registration access token:

| Request | Effect |
|---|---|
| `GET` | Returns the current registration. |
| `PUT` | Replaces the registration with the metadata sent. The body must contain `client_id`; a field left out is removed. The response carries a new registration access token. |
| `DELETE` | Deletes the application. Its users can no longer sign in to it. |

An administrator can edit or delete a dynamically registered application in the Admin Console like any other. Keep in mind that the client's next `PUT` overwrites the fields it owns (name, redirect URIs, grant types, client authentication, client URI and client keys). Assignments, policies, owners and the consent setting stay as the administrator set them.

## What a registered client can be

| Metadata | Rule |
|---|---|
| `token_endpoint_auth_method` | `client_secret_basic` (default), `client_secret_post`, `private_key_jwt` or `none`. |
| Application type | Derived from the client authentication: `none` creates a single-page application, or a native application when `"application_type": "native"` is sent or every redirect URI is a loopback address (`http://127.0.0.1`, `http://[::1]`, `http://localhost`) or an app-specific scheme. A native loopback redirect matches on any port. Every other method creates a web application. A native client must use `none`. |
| `grant_types` | Must contain `authorization_code`, may add `refresh_token`. Implicit, client credentials, device and token exchange grants are rejected. |
| `response_types` | `code` only. |
| `redirect_uris`, `post_logout_redirect_uris` | No wildcards, no URIs on the identity provider's own domain. |
| `client_uri` | Must use `https`. |
| `jwks` | Public keys only, RSA with at least 2048 bits or EC on the P-256 curve. Needed for `private_key_jwt`. |
| `jwks_uri`, `sector_identifier_uri`, `backchannel_logout_uri`, `request_uris` | Rejected, because the platform would have to call these URLs itself. An administrator can set the corresponding options on the application afterwards. |
| `client_name` | Optional. Without a name the application is called "Dynamic client" followed by its client ID. A name that is already taken gets part of the client ID appended. |
| `default_max_age` | Accepted. |

Any other metadata is ignored and not part of the response.

Some settings are always decided by the platform, whatever the request contains:

- **Require user consent** is switched on. Users confirm the requested access on first sign-in, and refresh tokens are only issued when the client requests the `offline_access` scope.
- No security profile is applied. An administrator can set one afterwards, see [Financial-grade API security](https://dts-identity.com/docs/integrations/applications.md#financial-grade-api-security).
- The application is not listed in the users' application portal.
- The administrator who issued the initial access token becomes the application's owner. Openly registered applications have no owner.

Registrations count towards the application limit of your subscription.

## Audit log

| Event | Logged when |
|---|---|
| `INITIAL_ACCESS_TOKEN_CREATED` | An administrator issues an initial access token. |
| `INITIAL_ACCESS_TOKEN_REVOKED` | An administrator revokes an initial access token. |
| `CONFIGURATION_UPDATED` | An administrator switches open registration on or off or changes its directories. |
| `APPLICATION_REGISTERED` | A client registers. The registering client is recorded as the actor. |
| `APPLICATION_UPDATED` | A client updates its registration. |
| `APPLICATION_DEREGISTERED` | A client deletes its registration, an administrator deletes the application, or an unused open registration is removed. |

See [Audit event types](https://dts-identity.com/docs/reference/audit-event-types.md) for the full list.

## Troubleshooting

- **`invalid_token` on registration:** the initial access token is unknown, expired, revoked, or a single-use token was already used. Issue a new one. Without a token, open registration is switched off.
- **`429` on an anonymous registration:** the rate limit of open registration is reached. Retry later.
- **`invalid_token` on read, update or delete:** the registration access token was replaced by a newer one on the last update, or the application was deleted.
- **`invalid_client_metadata` with "dynamic client registration is not available":** the subscription does not include the feature. Registrations and updates are rejected; reading and deleting an existing registration keep working.
- **`invalid_client_metadata`:** the metadata breaks one of the rules above. The `error_description` names the field. A rejected request does not use up a single-use token.
- **Users cannot sign in after registration:** the application has no assignments yet. Assign users, groups or directories on the application's **Assignments** tab. For an openly registered client, check that the user belongs to one of its directories.

## See also

- [Applications](https://dts-identity.com/docs/integrations/applications.md)
- [APIs](https://dts-identity.com/docs/integrations/apis.md)
- [Audit event types](https://dts-identity.com/docs/reference/audit-event-types.md)
