Create an OAuth client

Creates a client and mints its first secret, which the response carries once. A client_credentials client exchanges its client_id and secret for an access token at the provider's token endpoint. Requires the org:connect:write permission. Every requested scope must be a permission the caller holds. An AUTHORIZATION_CODE client must name at least one redirect URI, and every other grant must name none. Returns 400 when the redirect URIs do not match the grant type, 403 when a scope is not a permission the caller holds, and 422 when the provider refuses the request.

Authorization

oauth2

AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Header Parameters

Idempotency-Key*string

Unique key that de-duplicates retries of this request: the first call executes and its response is stored, identical retries replay it, and reusing a key with a different request body is rejected with 409 Conflict.

Lengthlength <= 255

Request Body

application/json

Request to create an OAuth client.

name*string

Human-readable name of the client. Up to 100 characters.

description?|

Free-text note about the client's purpose. Up to 255 characters. Absent when not set.

grant_type*string

How the client obtains a token. CLIENT_CREDENTIALS authenticates as the organization and names no user; it must name no redirect URI. AUTHORIZATION_CODE carries a signed-in user's consent and must name at least one redirect URI.

Value in

"CLIENT_CREDENTIALS"
"AUTHORIZATION_CODE"

scopes*array<>

Permissions to grant. Every one must be a permission the caller holds. Read GET /v1/oauth/clients/scopes for the list.

Items1 <= items

redirect_uris?array<>

Where the provider returns the authorization code. Required for AUTHORIZATION_CODE and refused for every other grant. Every such client uses PKCE; it is not an option.

Response Body

`application/json`

curl -X POST "https://example.com/v1/oauth/clients" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "name": "Point of Sale Integration",    "description": "Point of sale integration for Nairobi branches",    "grant_type": "CLIENT_CREDENTIALS",    "scopes": [      "org:accounts:read"    ],    "redirect_uris": []  }'

{  "id": "app_2c9f8b3e1a7d4f56",  "client_id": "client_2c9f8b3e1a7d4f56",  "name": "Point of Sale Integration",  "description": "Point of sale integration for Nairobi branches",  "grant_type": "CLIENT_CREDENTIALS",  "scopes": [    "org:accounts:read"  ],  "redirect_uris": [    {      "uri": "https://partner.example.com/callback/cowdi",      "is_default": true    }  ],  "client_secret": "oauth_client_secret_example_abc123def456ghi789",  "created_at": "2026-09-01T10:15:30Z"}

{  "code": "BAD_REQUEST",  "description": "Bad Request"}

{  "code": "UNAUTHORISED",  "description": "Unauthorised"}

{  "code": "FORBIDDEN",  "description": "Forbidden"}

{  "code": "BAD_REQUEST",  "description": "Invalid input"}

{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}

{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`