Cowdidocs
API ReferenceOAuth clients

Rotate the client secret

POST
/v1/oauth/clients/{oauthClientId}/secrets

Mints a second secret so the holder can roll over. Deploy it, wait for last_used_at on the old secret to stop moving, then revoke the old one with the revoke a client secret operation. Requires the org:connect:write permission. Returns 404 when the caller's organization has no client with this id, and 409 when the client already holds the maximum number of secrets.

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.

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/oauth/clients/app_2c9f8b3e1a7d4f56/secrets" \  -H "Idempotency-Key: string"
{  "id": "sec_8f14e45fceea167a",  "secret": "oauth_client_secret_example_abc123def456ghi789",  "secret_hint": "a1b2",  "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": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List the secrets of an OAuth client GET

Lists a client's secrets, with their hints and last-used times. The plain text is not readable here; it is shown once, when the secret is minted. Requires the `org:connect:read` permission. Returns 404 when the caller's organization has no client with this id.

Revoke a client secret DELETE

Revokes one secret of an OAuth client. Read `last_used_at` on the rotate the client secret response first, to confirm the holder has moved to the new secret. Requires the `org:connect:write` permission. Returns 404 when the caller's organization has no client with this id, or the client has no such secret.