Register an OAuth app

POST/oauth/apps

Signed inBeta: may change

A new app and its client id. A confidential app’s client secret is in this answer only. Apps asking for write or store scopes work for you alone until an admin approves them.

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

Request body required · application/json

CreateOAuthApp

namestringrequired
2–60 characters
descriptionstring or null
at most 300 characters
homepageUrlstringrequired
at most 500 characters
privacyUrlstringrequired
Required: the consent screen links it.
at most 500 characters
termsUrlstring or null
at most 500 characters
redirectUrisarray of stringrequired
Exact matches: https, or http on 127.0.0.1, [::1] or localhost (whose port may differ in a request).
1–10 items
scopesarray of enumrequired
Personal or store scopes from the API key catalogue; never admin scopes.
1–40 items
One ofcatalog:readcollection:readcollection:writewishlist:readwishlist:writescans:write
and 31 more
scans:readlabels:readlabels:writeinsights:readinsights:writeexports:readholds:readholds:writequestions:readquestions:writeaccount:readaccount:writereports:writestores:readstores:writeassistant:usewebhooks:readwebhooks:writestore:readstore:inventory:readstore:inventory:writestore:holds:readstore:holds:writestore:questions:readstore:questions:writestore:storefront:writestore:staff:readstore:staff:writestore:billing:readstore:webhooks:readstore:webhooks:write
clientTypeenumrequired
One ofpublicconfidential

Responses

201CreatedThe new app (and its 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.

7Errors400 · 401 · 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).
409
too_many_apps
too_many_apps: Already 10 apps: delete one first.
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' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Shelfie",
    "description": "Your collection on a shelf you can share.",
    "homepageUrl": "https://shelfie.example",
    "privacyUrl": "https://shelfie.example/privacy",
    "redirectUris": [
      "https://shelfie.example/callback",
      "http://127.0.0.1/callback"
    ],
    "scopes": [
      "catalog:read",
      "collection:read",
      "collection:write"
    ],
    "clientType": "confidential"
  }'

{
  "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_Xq3b…",
      "createdAt": "2026-10-13T06:47:11.610Z",
      "previousExpiresAt": null
    },
    "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"
}

Request body required · application/json

CreateOAuthApp

namestringrequired
2–60 characters
descriptionstring or null
at most 300 characters
homepageUrlstringrequired
at most 500 characters
privacyUrlstringrequired
Required: the consent screen links it.
at most 500 characters
termsUrlstring or null
at most 500 characters
redirectUrisarray of stringrequired
Exact matches: https, or http on 127.0.0.1, [::1] or localhost (whose port may differ in a request).
1–10 items
scopesarray of enumrequired
Personal or store scopes from the API key catalogue; never admin scopes.
1–40 items
One ofcatalog:readcollection:readcollection:writewishlist:readwishlist:writescans:write
and 31 more
scans:readlabels:readlabels:writeinsights:readinsights:writeexports:readholds:readholds:writequestions:readquestions:writeaccount:readaccount:writereports:writestores:readstores:writeassistant:usewebhooks:readwebhooks:writestore:readstore:inventory:readstore:inventory:writestore:holds:readstore:holds:writestore:questions:readstore:questions:writestore:storefront:writestore:staff:readstore:staff:writestore:billing:readstore:webhooks:readstore:webhooks:write
clientTypeenumrequired
One ofpublicconfidential

Responses

201CreatedThe new app (and its 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.

7Errors400 · 401 · 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).
409
too_many_apps
too_many_apps: Already 10 apps: delete one first.
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' \ -H "Authorization: Bearer $COLLECTOR_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "name": "Shelfie", "description": "Your collection on a shelf you can share.", "homepageUrl": "https://shelfie.example", "privacyUrl": "https://shelfie.example/privacy", "redirectUris": [ "https://shelfie.example/callback", "http://127.0.0.1/callback" ], "scopes": [ "catalog:read", "collection:read", "collection:write" ], "clientType": "confidential" }'

{ "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_Xq3b…", "createdAt": "2026-10-13T06:47:11.610Z", "previousExpiresAt": null }, "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" }