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,
    • "redirect_uris": [],
    • "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
    }
]
Register a Client Application
OAuth 2.0: okta.clients.register
Registers a new client application




Note: You can create apps 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. The following grant types are only : 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





native
authorization_code, implicit, password, refresh_token, urn:ietf:params:oauth:grant-type:saml2-bearer. The following grant types are only : 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
Must have at least authorization_code




service
client_credentials, urn:ietf:params:oauth:grant-type:saml2-bearer. The following grant types are only : 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
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. The following grant types are only : 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
Must have at least authorization_code







Note: The client_credentials grant with a web Application type allows you to use one client_id for an Application that needs to make user-specific calls and back-end calls for data.






Note: The grant_types and response_types values described above are partially orthogonal, as they refer to arguments passed to different endpoints in the OAuth 2.0 protocol. However, they are related in that the grant_types available to a client influence the response_types that the client is allowed to use and vice versa. For instance, a grant_types value that includes authorization_code implies a response_types value that includes code, as both values are defined as part of the OAuth 2.0 Authorization Code grant.




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
required
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 sign-in flow by the client


 
object
A JSON Web Key Set for validating JWTs presented to Okta


 
Array of objects (JsonWebKey) 
 
 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 you must use for signing request objects. When you specify a value for the request_object_signing_alg property, all request objects from the client are rejected if not signed with the specified algorithm. You must use the algorithm when the request object is passed by value (using the request parameter). If a value for request_object_signing_alg isn't specified, the default is any algorithm that's supported by both the client and the server.


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
CORS
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
required
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 sign-in flow by the client


 
object
A JSON Web Key Set for validating JWTs presented to Okta


 
Array of objects (JsonWebKey) 
 
 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 you must use for signing request objects. When you specify a value for the request_object_signing_alg property, all request objects from the client are rejected if not signed with the specified algorithm. You must use the algorithm when the request object is passed by value (using the request parameter). If a value for request_object_signing_alg isn't specified, the default is any algorithm that's supported by both the client and the server.


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
{}