Dynamic Client Registration

The Dynamic Client Registration API provides operations to register and manage client Applications for use with Okta's OAuth 2.0 and OpenID Connect endpoints. This API largely follows the contract defined in RFC7591: OAuth 2.0 Dynamic Client Registration Protocol and OpenID Connect Dynamic Client Registration 1.0.

Note: Clients managed through this API are modeled as Applications in Okta and appear in the Applications section of the Admin Console. Changes made through the API appear in the UI and vice versa. Tokens issued by these clients follow the rules for access tokens and ID tokens.

List all Client Applications
OAuth 2.0: okta.clients.read

Lists all the client applications with pagination

Request
query Parameters
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination for more information.

Note: The after cursor should be treated as an opaque value and obtained through the next link relation.

limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return.

q
string

Searches the client_name property of clients for matching value.

Note: Search currently performs a startsWith match, but this is an implementation detail and may change without notice.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/oauth2/v1/clients
Request samples
Response samples
application/json
[
  • {
    • "client_id": "B6YnDUIpt6Oq354YYaNR",
    • "client_id_issued_at": 1495059435,
    • "client_secret_expires_at": 0,
    • "client_name": "Native client",
    • "client_uri": null,
    • "logo_uri": null,
    • "redirect_uris": [],
    • "response_types": [
      ],
    • "grant_types": [
      ],
    • "token_endpoint_auth_method": "client_secret_basic",
    • "application_type": "native",
    • "frontchannel_logout_uri": "https://example.com/logout",
    • "frontchannel_logout_session_required": false
    },
  • {
    • "client_id": "etwquEhEjxqyA7HDB8lD",
    • "client_id_issued_at": 1495059868,
    • "client_secret_expires_at": 0,
    • "client_name": "Service client",
    • "client_uri": null,
    • "logo_uri": null,
    • "redirect_uris": [ ],
    • "response_types": [
      ],
    • "grant_types": [
      ],
    • "token_endpoint_auth_method": "client_secret_basic",
    • "application_type": "service",
    • "frontchannel_logout_uri": "https://example.com/logout",
    • "frontchannel_logout_session_required": false
    },
  • {
    • "client_id": "l3O8MfR0eTVfLJ7jG2UB",
    • "client_id_issued_at": 1495059734,
    • "client_name": "Browser client",
    • "client_uri": null,
    • "logo_uri": null,
    • "redirect_uris": [],
    • "response_types": [
      ],
    • "grant_types": [
      ],
    • "token_endpoint_auth_method": "none",
    • "application_type": "browser"
    },
  • {
    • "client_id": "rHQoApjizqc4MGVlW5En",
    • "client_id_issued_at": 1495059117,
    • "client_secret_expires_at": 0,
    • "client_name": "Web client",
    • "client_uri": null,
    • "logo_uri": null,
    • "response_types": [
      ],
    • "grant_types": [
      ],
    • "token_endpoint_auth_method": "client_secret_basic",
    • "application_type": "web",
    • "frontchannel_logout_uri": "https://example.com/logout",
    • "frontchannel_logout_session_required": false
    }
]

Create a Client Application
OAuth 2.0: okta.clients.register

Creates a new client application.

Note: Apps can be created on the Apps endpoint (/api/v1/apps) and default to consent_method=TRUSTED, while those created with Dynamic Client Registration (/oauth2/v1/clients) default to consent_method=REQUIRED."

Note: If you want to specify the client_id or client_secret, you can use Apps API to create or update a client Application.

Different Application types have different valid values for the corresponding grant type:

Application Type Valid Grant Type Requirements
browser authorization_code, implicit, urn:ietf:params:oauth:grant-type:saml2-bearer
native authorization_code, implicit, password, refresh_token, urn:ietf:params:oauth:grant-type:saml2-bearer Must have at least authorization_code
service client_credentials, urn:ietf:params:oauth:grant-type:saml2-bearer Works with OAuth 2.0 flow (not OpenID Connect)
web authorization_code, implicit, refresh_token, client_credentials(*), urn:ietf:params:oauth:grant-type:saml2-bearer Must have at least authorization_code
Request
Request Body schema: application/json
required
application_type
string (ApplicationType)

The type of client application. Default value: web.

Enum: "browser" "native" "service" "web"
client_name
string

Human-readable string name of the client application

frontchannel_logout_session_required
boolean

Include user session details

frontchannel_logout_uri
string or null

URL where Okta sends the logout request

grant_types
Array of strings (GrantType)

Array of OAuth 2.0 grant type strings. Default value: [authorization_code]

Items Enum: "authorization_code" "client_credentials" "implicit" "interaction_code" "password" "refresh_token" "urn:ietf:params:oauth:grant-type:device_code" "urn:ietf:params:oauth:grant-type:jwt-bearer" "urn:ietf:params:oauth:grant-type:saml2-bearer" "urn:ietf:params:oauth:grant-type:token-exchange" "urn:openid:params:grant-type:ciba" "urn:okta:params:oauth:grant-type:otp" "urn:okta:params:oauth:grant-type:oob" "http://auth0.com/oauth/grant-type/mfa-otp" "http://auth0.com/oauth/grant-type/mfa-oob"
initiate_login_uri
string

URL that a third party can use to initiate a login by the client

Array of objects (JsonWebKey)

A JSON Web Key Set for validating JWTs presented to Okta

Array
alg
string (SigningAlgorithm)
Enum: "ES256" "ES384" "ES512" "HS256" "HS384" "HS512" "RS256" "RS384" "RS512"
kid
string

The unique identifier of the key

kty
string (JsonWebKeyType)

The type of public key

status
string (JsonWebKeyStatus)

The status of the public key

Enum: "ACTIVE" "INACTIVE"
use
string (JsonWebKeyUse)

The intended use of the public key

Enum: "enc" "sig"
x
string

The public x coordinate for the elliptic curve point

y
string

The public y coordinate for the elliptic curve point

jwks_uri
string

URL string that references a JSON Web Key Set for validating JWTs presented to Okta

logo_uri
string or null

URL string that references a logo for the client consent dialog (not the sign-in dialog)

policy_uri
string or null

URL string of a web page providing the client's policy document

post_logout_redirect_uris
string

Array of redirection URI strings for use for relying party initiated logouts

redirect_uris
Array of strings

Array of redirection URI strings for use in redirect-based flows. All redirect URIs must be absolute URIs and must not include a fragment component. At least one redirect URI and response type is required for all client types, with the following exceptions: If the client uses the Resource Owner Password flow (if grant_type contains the value password) or the Client Credentials flow (if grant_type contains the value client_credentials), then no redirect URI or response type is necessary. In these cases, you can pass either null or an empty array for these attributes.

request_object_signing_alg
Array of strings (SigningAlgorithm)

The type of JSON Web Key Set algorithm that must be used for signing request objects

Items Enum: "ES256" "ES384" "ES512" "HS256" "HS384" "HS512" "RS256" "RS384" "RS512"
response_types
Array of strings (ResponseType)

Array of OAuth 2.0 response type strings. Default value: [code]

Items Enum: "code" "id_token" "none" "token"
token_endpoint_auth_method
string (EndpointAuthMethod)

Requested authentication method for OAuth 2.0 endpoints.

Enum: "client_secret_basic" "client_secret_jwt" "client_secret_post" "none" "private_key_jwt"
tos_uri
string or null

URL string of a web page providing the client's terms of service document

Responses
201

Created

400

Bad Request

403

Forbidden

429

Too Many Requests

post/oauth2/v1/clients
Request samples
application/json
{}
Response samples
application/json
{}

Retrieve a Client application
OAuth 2.0: okta.clients.read

Retrieves a Client application by clientId

Request
path Parameters
clientId
required
string

client_id of the Client application

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/oauth2/v1/clients/{clientId}
Request samples
Response samples
application/json
{}

Replace a Client Application
OAuth 2.0: okta.clients.manage

Replaces the settings for a client application.

Note: You must specifiy all settings when you update a client Application. Partial updates aren't supported. If any settings are missing when you update a client application, the update fails. The exceptions are that you can't include client_secret_expires_at or client_id_issued_at in the request, and you can omit the client_secret.

Request
path Parameters
clientId
required
string

client_id of the Client application

Request Body schema: application/json
required
application_type
string (ApplicationType)

The type of client application. Default value: web.

Enum: "browser" "native" "service" "web"
client_name
string

Human-readable string name of the client application

frontchannel_logout_session_required
boolean

Include user session details

frontchannel_logout_uri
string or null

URL where Okta sends the logout request

grant_types
Array of strings (GrantType)

Array of OAuth 2.0 grant type strings. Default value: [authorization_code]

Items Enum: "authorization_code" "client_credentials" "implicit" "interaction_code" "password" "refresh_token" "urn:ietf:params:oauth:grant-type:device_code" "urn:ietf:params:oauth:grant-type:jwt-bearer" "urn:ietf:params:oauth:grant-type:saml2-bearer" "urn:ietf:params:oauth:grant-type:token-exchange" "urn:openid:params:grant-type:ciba" "urn:okta:params:oauth:grant-type:otp" "urn:okta:params:oauth:grant-type:oob" "http://auth0.com/oauth/grant-type/mfa-otp" "http://auth0.com/oauth/grant-type/mfa-oob"
initiate_login_uri
string

URL that a third party can use to initiate a login by the client

Array of objects (JsonWebKey)

A JSON Web Key Set for validating JWTs presented to Okta

Array
alg
string (SigningAlgorithm)
Enum: "ES256" "ES384" "ES512" "HS256" "HS384" "HS512" "RS256" "RS384" "RS512"
kid
string

The unique identifier of the key

kty
string (JsonWebKeyType)

The type of public key

status
string (JsonWebKeyStatus)

The status of the public key

Enum: "ACTIVE" "INACTIVE"
use
string (JsonWebKeyUse)

The intended use of the public key

Enum: "enc" "sig"
x
string

The public x coordinate for the elliptic curve point

y
string

The public y coordinate for the elliptic curve point

jwks_uri
string

URL string that references a JSON Web Key Set for validating JWTs presented to Okta

logo_uri
string or null

URL string that references a logo for the client consent dialog (not the sign-in dialog)

policy_uri
string or null

URL string of a web page providing the client's policy document

post_logout_redirect_uris
string

Array of redirection URI strings for use for relying party initiated logouts

redirect_uris
Array of strings

Array of redirection URI strings for use in redirect-based flows. All redirect URIs must be absolute URIs and must not include a fragment component. At least one redirect URI and response type is required for all client types, with the following exceptions: If the client uses the Resource Owner Password flow (if grant_type contains the value password) or the Client Credentials flow (if grant_type contains the value client_credentials), then no redirect URI or response type is necessary. In these cases, you can pass either null or an empty array for these attributes.

request_object_signing_alg
Array of strings (SigningAlgorithm)

The type of JSON Web Key Set algorithm that must be used for signing request objects

Items Enum: "ES256" "ES384" "ES512" "HS256" "HS384" "HS512" "RS256" "RS384" "RS512"
response_types
Array of strings (ResponseType)

Array of OAuth 2.0 response type strings. Default value: [code]

Items Enum: "code" "id_token" "none" "token"
token_endpoint_auth_method
string (EndpointAuthMethod)

Requested authentication method for OAuth 2.0 endpoints.

Enum: "client_secret_basic" "client_secret_jwt" "client_secret_post" "none" "private_key_jwt"
tos_uri
string or null

URL string of a web page providing the client's terms of service document

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/oauth2/v1/clients/{clientId}
Request samples
application/json
{}
Response samples
application/json
{}

Delete a Client Application
OAuth 2.0: okta.clients.manage

Deletes a client application

Request
path Parameters
clientId
required
string

client_id of the Client application

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/oauth2/v1/clients/{clientId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Generate a new client secret
OAuth 2.0: okta.clients.manage

Generates a new client secret for the specified client Application.

Note: This operation only applies to client Applications that use the client_secret_post or client_secret_basic method for token endpoint authorization.

Request
path Parameters
clientId
required
string

client_id of the Client application

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/oauth2/v1/clients/{clientId}/lifecycle/newSecret
Request samples
Response samples
application/json
{}