Skip to content

Admin API scopes

An admin API key lets your backend, a script or an AI assistant call the Admin API. Each key holds a set of scopes, and each route needs particular scopes. Give each key the fewest scopes that do its job.

An organization owner creates keys in the Console, on the API keys page. Choose the scopes and, if you like, an expiry. The key is shown once, so copy it into your server’s secrets straight away.

A key reads sc_<prefix>_<secret>: sc_, a 12-character prefix, _ and the secret. Send it on every call:

Terminal window
curl https://api.sealcord.com/v1/admin/licences/counts \
-H "authorization: Bearer $SEALCORD_TOKEN"

Keep it on your server, never in your app, a web page or a repository. Sealcord stores only a hash of the key, so it cannot show it again. If you lose it, create another and revoke the old one. The admin API cannot create keys itself: it needs a signed-in owner.

A new key works within 5 seconds. A call without a valid key answers 401 unauthorized. A call with a key that lacks a scope answers 403 insufficient_scope, and details.missing lists the scopes to add.

Scope Allows
products:read List and read products
products:write Create and update products, rotate their signing keys and retire previous public keys
licences:read Find licences, and read one with its key and activations
licences:write Issue, revoke, expire and reinstate licences, and free an activation
licences:anonymise Anonymise a licence: erase its customer’s data. It cannot be undone
audit:read Read a licence’s audit log
payments:read List your payment integrations (never their credentials) and their product mappings
payments:write Create, change and delete an integration’s product mappings, whatever the provider
organization:read Read the organization: name, slug, plan and its team places. No billing detail
members:read Read the members, with their emails and roles, and invitations not yet accepted or revoked
members:write Invite, revoke an invitation, change a role and remove a member. Never held by a key
webhooks:read List and read webhook endpoints (never their secrets) and their deliveries
webhooks:write Add, change and remove webhook endpoints, replace their secrets and retry deliveries
workspaces:read List your own workspaces and your role in each. Never held by a key
workspaces:write Create a workspace you own, and move a product between two you own. Never held by a key

polar:read and polar:write are the old names of payments:read and payments:write. Keys that hold them keep working, and each grants the new scope.

licences:read reveals licence keys and customer email addresses. Grant it only where a key or an address is needed.

Route group Scopes
Products, rotating a signing key, retiring a public key products:read, products:write
Issue, search, read, count, revoke, expire, reinstate licences:read, licences:write
Free a machine by activation id licences:write
Anonymise a licence licences:anonymise
A licence’s audit log audit:read
Payment integrations and their mappings payments:read, payments:write
Webhook endpoints and deliveries webhooks:read, webhooks:write
The organization, members and invitations organization:read, members:read
Your workspaces; creating one; moving a product workspaces:read, workspaces:write

Each route’s page in the API reference names the scope it needs.

  • Connecting a payment integration, checking or disconnecting it, and setting its webhook secret. These are the Console’s, for owners and admins.
  • Changing the team with a key. members:write is granted only to an AI assistant that a member signs in through the MCP server. Each change runs as that member, held to their role at that moment, because an invitation always names who sent it. No admin API key holds it.
  • Managing workspaces with a key. workspaces:read and workspaces:write are a person’s: the workspaces they belong to, a new one they own, and moving a product between two they own. Only an AI assistant a member connects through the MCP server is granted them; a key belongs to one workspace.
  • Granting licences:anonymise or products:write to an assistant. No assistant is granted either: they need an admin API key.
  • Adding or changing a webhook endpoint through an assistant. An assistant can read endpoints and deliveries and retry a delivery. Adding, changing or removing an endpoint and replacing its secret need a key of your organization with webhooks:write.

A key made in the Console belongs to the organization it was created in. It sees and changes only that organization’s products, the licences of those products, their activations and their audit logs. A row from another organization answers exactly as a missing one does (licence_not_found, product_not_found), never 403, which would confirm the row exists.

An organization’s key creates products of its own and rotates their signing keys, which Sealcord generates and stores. It cannot name a signing key of its own.

Job Scopes
Issue and end licences from your checkout licences:read, licences:write
A support assistant that only reads products:read, licences:read, audit:read, payments:read
Show licence counts on an internal dashboard licences:read
Manage webhook endpoints from a script webhooks:read, webhooks:write
Map Polar or Stripe products from a script payments:read, payments:write

Which scopes does a checkout backend need?

Section titled “Which scopes does a checkout backend need?”

licences:read and licences:write. Writing issues, revokes, expires and reinstates; reading lets you look a licence up by its id or external reference before you retry. See issue licences from your backend.

No. Keys are created in the Console by an organization owner.

Revoke it in the Console and create another. A revoked key answers 401 unauthorized.

Does a key work for more than one organization?

Section titled “Does a key work for more than one organization?”

No. A key belongs to the organization it was created in and reaches nothing else.