Rotate an OAuth app’s client secret

POST/oauth/apps/{appId}/secret

Signed inBeta: may change

A new client secret, shown in this answer only. The old one stops at once, or after 24 hours with graceHours: 24.

SDK method: collector.rotateMyOAuthAppSecret()
Headers: X-Request-Id

Path parameters

appIdstring (uuid)required

Request body optional · application/json

RotateOAuthSecret

graceHours"0" or "24"
Keep the old secret working this many hours, so your servers can switch over.
default 0
ShowHide the fields of graceHours
1. Option 1: "0"
2. Option 2: "24"

Responses

201CreatedThe new secret, shown once.

NewOAuthApp

An app just made (or its secret just rotated): the only time its secret is shown.

appOAuthApprequired
clientSecretstring or nullrequired
A confidential app’s client secret. Store it now: it can’t be shown again.

8Errors400 · 401 · 404 · 409 · 413 · 429 · 500 · 503

400
invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found
not_found: Nothing at that address.
409
not_confidential secret_changed
not_confidential: A public app has no secret.
secret_changed: Rotated by another request at the same moment: try again.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).
503
api_keys_unavailable
api_keys_unavailable: This deployment isn’t set up for API keys and OAuth.

curl -X POST 'https://api.collection.id/v1/oauth/apps/5e7a9c1b-3d2f-4a6e-8b0c-1d3f5a7b9c2e/secret' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "graceHours": 24
  }'

{
  "app": {
    "id": "5e7a9c1b-3d2f-4a6e-8b0c-1d3f5a7b9c2e",
    "clientId": "app_k3v9q2m7x1c8d4f6h0j5",
    "clientType": "confidential",
    "name": "Shelfie",
    "description": "Your collection on a shelf you can share.",
    "homepageUrl": "https://shelfie.example",
    "privacyUrl": "https://shelfie.example/privacy",
    "termsUrl": null,
    "logoPath": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90/app-3f2a9c.webp",
    "logoUrl": "https://example.supabase.co/storage/v1/object/public/avatars/6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90/app-3f2a9c.webp",
    "redirectUris": [
      "https://shelfie.example/callback",
      "http://127.0.0.1/callback"
    ],
    "scopes": [
      "catalog:read",
      "collection:read",
      "collection:write"
    ],
    "secret": {
      "display": "ccs_live_Jm8w…",
      "createdAt": "2026-10-13T06:47:11.610Z",
      "previousExpiresAt": "2026-10-14T06:47:11.610Z"
    },
    "review": {
      "status": "unreviewed",
      "approvedScopes": [],
      "awaitingScopes": [
        "collection:write"
      ],
      "note": null,
      "requestedAt": null,
      "reviewedAt": null
    },
    "suspendedAt": null,
    "suspendedReason": null,
    "connections": 0,
    "createdAt": "2026-10-13T06:47:11.610Z",
    "updatedAt": "2026-10-13T06:47:11.610Z"
  },
  "clientSecret": "ccs_live_Xq3bEXAMPLE-shown-once-store-it-safely-0000"
}

Responses

201CreatedThe new secret, shown once.

NewOAuthApp

An app just made (or its secret just rotated): the only time its secret is shown.

appOAuthApprequired
clientSecretstring or nullrequired
A confidential app’s client secret. Store it now: it can’t be shown again.

8Errors400 · 401 · 404 · 409 · 413 · 429 · 500 · 503

400
invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found
not_found: Nothing at that address.
409
not_confidential secret_changed
not_confidential: A public app has no secret.
secret_changed: Rotated by another request at the same moment: try again.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).
503
api_keys_unavailable
api_keys_unavailable: This deployment isn’t set up for API keys and OAuth.

curl -X POST 'https://api.collection.id/v1/oauth/apps/5e7a9c1b-3d2f-4a6e-8b0c-1d3f5a7b9c2e/secret' \ -H "Authorization: Bearer $COLLECTOR_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "graceHours": 24 }'

{ "app": { "id": "5e7a9c1b-3d2f-4a6e-8b0c-1d3f5a7b9c2e", "clientId": "app_k3v9q2m7x1c8d4f6h0j5", "clientType": "confidential", "name": "Shelfie", "description": "Your collection on a shelf you can share.", "homepageUrl": "https://shelfie.example", "privacyUrl": "https://shelfie.example/privacy", "termsUrl": null, "logoPath": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90/app-3f2a9c.webp", "logoUrl": "https://example.supabase.co/storage/v1/object/public/avatars/6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90/app-3f2a9c.webp", "redirectUris": [ "https://shelfie.example/callback", "http://127.0.0.1/callback" ], "scopes": [ "catalog:read", "collection:read", "collection:write" ], "secret": { "display": "ccs_live_Jm8w…", "createdAt": "2026-10-13T06:47:11.610Z", "previousExpiresAt": "2026-10-14T06:47:11.610Z" }, "review": { "status": "unreviewed", "approvedScopes": [], "awaitingScopes": [ "collection:write" ], "note": null, "requestedAt": null, "reviewedAt": null }, "suspendedAt": null, "suspendedReason": null, "connections": 0, "createdAt": "2026-10-13T06:47:11.610Z", "updatedAt": "2026-10-13T06:47:11.610Z" }, "clientSecret": "ccs_live_Xq3bEXAMPLE-shown-once-store-it-safely-0000" }