API ReferenceOAuth Clients

Create OAuth Client

Create a new OAuth client for API access. OAuth clients enable: - Third-party application integration - Service-to-service authentication - Mobile app authentication - CLI tool access Configure grant types based on your use case: - **authorization_code**: Web applications with backend - **client_credentials**: Service-to-service auth - **refresh_token**: Long-lived access - **implicit**: Single-page applications (deprecated) **PKCE Support**: - Enable PKCE for public clients (mobile apps, SPAs) - Supports S256 (SHA-256) and plain challenge methods - Required for clients without client secrets The client secret is returned only once - store it securely!

Authentication

AuthorizationBearer

Bearer token authentication using JWT tokens from Ory Kratos/Hydra

Path Parameters

org_idstringRequiredformat: "uuid"
The unique identifier of the organization.
project_idstringRequiredformat: "uuid"
The unique identifier of the project.

Request

This endpoint expects an object.
namestring or nullOptional1-255 characters
Name for the new OAuth client. Must be between 1 and 255 characters. Optional for predefined profiles.
profileenumOptional

Client profile type that determines behavior and capabilities. Usually USER_DEFINED for custom clients.

redirect_urislist of strings or nullOptional

List of authorized callback URLs for OAuth flows. Required if using authorization_code or implicit grant types.

scopesstringOptional0-255 charactersDefaults to

Space-separated list of requested OAuth scopes. Default is empty string for minimal access.

access_token_typeenumOptional
Type of access token to issue: - opaque: Non-transparent token requiring validation - jwt: Self-contained JSON Web Token
Allowed values:
grant_typeslist of enums or nullOptional
List of OAuth grant types to enable. Choose based on your application type and security requirements.
Allowed values:
token_endpoint_auth_methodenumOptionalDefaults to client_secret_basic
Authentication method enabled for the client: - client_secret_basic: Client ID and secret sent in HTTP headers - client_secret_post: Client ID and secret sent in request body - none: No client authentication (required for public clients using PKCE)
Allowed values:
pkce_requiredbooleanOptionalDefaults to false

Whether to require PKCE (Proof Key for Code Exchange) for authorization code flows. PKCE adds security by requiring a code_challenge and code_verifier. IMPORTANT: Only applicable when ‘authorization_code’ is included in grant_types. Highly recommended for public clients (mobile apps, SPAs) and beneficial for all clients.

pkce_challenge_methodenumOptional
PKCE code challenge method when PKCE is enabled. - S256: SHA256 hash of code verifier (recommended and secure) - plain: Plain text code verifier (not recommended, only for testing)
Allowed values:

Response

Successful Response
idstringformat: "uuid"
Unique identifier for the OAuth client.
namestring

Human-readable name for the OAuth client.

client_idstringformat: "uuid"
Unique identifier used to identify the client with the authorization server.
project_idstringformat: "uuid"
ID of the project this OAuth client belongs to.
createdstring
Timestamp when the OAuth client was created.
modifiedstring
Timestamp when the OAuth client was last modified.
descriptionstring or null
Optional description explaining the client's purpose and usage.
redirect_urislist of strings or null

List of authorized redirect URIs for OAuth flows requiring user interaction. Required for authorization code and implicit flows. Must be exact matches when used. Must use HTTPS in production (except for localhost).

grant_typeslist of enums or null
OAuth 2.0 grant types enabled for this client. - client_credentials: For server-to-server API access - authorization_code: For web and mobile apps - refresh_token: For maintaining long-term access - implicit: Legacy flow, not recommended for new applications
Allowed values:
client_secretstring or null

Secret key used to authenticate the client. Only shown once upon creation. Must be stored securely. Required for confidential clients (e.g., server applications).

token_endpoint_auth_methodenum or nullDefaults to client_secret_basic
Authentication method enabled for the client: - client_secret_basic: Client ID and secret sent in HTTP headers - client_secret_post: Client ID and secret sent in request body - none: No client authentication (required for public clients using PKCE)
Allowed values:
pkce_requiredboolean or nullDefaults to false

Whether PKCE (Proof Key for Code Exchange) is required for this client. When enabled, authorization code flows must include code_challenge and code_verifier. Recommended for public clients (mobile apps, SPAs) and enhances security for all clients.

pkce_challenge_methodenum or null
PKCE code challenge method when PKCE is enabled. - S256: SHA256 hash of code verifier (recommended and secure) - plain: Plain text code verifier (not recommended, only for testing)
Allowed values:

Errors