Cowdidocs
API ReferenceOAuth clients

Read one OAuth client

GET
/v1/oauth/clients/{oauthClientId}

Reads one OAuth client of the caller's organization, without its secrets. Requires the org:connect:read permission. Returns 404 when the caller's organization has no client with this id.

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

Path Parameters

oauthClientId*string

Unique identifier of the OAuth client.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/oauth/clients/app_2c9f8b3e1a7d4f56"
{  "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    }  ],  "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"}

Create an OAuth client POST

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.

Update an OAuth client PATCH

Carries the whole editable record, so every field is set on every call. Requires the `org:connect:write` permission. Every requested scope must be a permission the caller holds, and the redirect URIs must match the client's grant type. Returns 400 when the redirect URIs do not match the grant type, 403 when a scope is not a permission the caller holds, 404 when the caller's organization has no client with this id, and 422 when the provider refuses the request.