---
title: Dynamic registration API
description: Register an OIDC client with an IAT, read its metadata, and remove
  its registration.
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Use dynamic registration when an RP needs to create a client under approved organization authority. Obtain an [Initial Access Token (IAT)](/en-us/oidc/registration-access/) first. Read `registration_endpoint` from discovery.

## 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`:

```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:

```bash
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.

```json
{
  "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

| 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](/en-us/oidc/relying-party-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](/en-us/oidc/advanced/). |
| 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

Use the returned `registration_client_uri` and that client's RAT:

```bash
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

```bash
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

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](/en-us/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.

## Related

- [IAT and RAT management](/en-us/oidc/registration-access/)
- [Organization application templates](/en-us/with-portal/application-templates/)
- [OIDC flow](/en-us/oidc/flow/)