Cowdidocs
API ReferenceOAuth clients

List OAuth clients

GET
/v1/oauth/clients

Lists every OAuth client of the caller's organization, on one page. Requires the org:connect:read permission. Secrets are not carried here; list them separately through the list client secrets operation.

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/oauth/clients"
{  "data": [    {      "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"    }  ],  "links": {    "next": "/v1/payees?after=eyJpZCI6MX0",    "prev": "/v1/payees?before=eyJpZCI6MX0"  }}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Sign in with a custom token POST

Exchanges a custom token for an ID token and a refresh token. Any client can call it without a Cowdi access token. The custom token comes from a token exchange operation. Returns 400 with `INVALID_TOKEN` when the custom token is invalid or Firebase rejects it. Returns 503 with `SERVICE_TEMPORARILY_UNAVAILABLE` when Firebase is not available. Send the same request again later. Use the ID token as the Bearer token for API calls, and refresh it through `/v1/auth/refresh` before it expires.

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.