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.
Create a key
Section titled “Create a key”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:
curl https://api.sealcord.com/v1/admin/licences/counts \ -H 'authorization: Bearer sc_<prefix>_<secret>'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.
The scopes
Section titled “The scopes”| 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 |
polar:read |
List your payment integrations (never their credentials) and their Polar mappings |
polar:write |
Create, change and delete an integration’s Polar mappings |
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 |
licences:read reveals licence keys and customer email addresses. Grant it only where a key or
an address is needed.
Which routes need which scope
Section titled “Which routes need which scope”| 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 | polar:read, polar:write |
| Webhook endpoints and deliveries | webhooks:read, webhooks:write |
| The organization, members and invitations | organization:read, members:read |
Each route’s page in the API reference names the scope it needs.
What no scope allows
Section titled “What no scope allows”- 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:writeis 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. - Granting
licences:anonymiseorproducts:writeto 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.
Organization scope
Section titled “Organization scope”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.
Suggested scopes
Section titled “Suggested scopes”| 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, polar:read |
| Show licence counts on an internal dashboard | licences:read |
| Manage webhook endpoints from a script | webhooks:read, webhooks:write |
| Map Polar products from a script | polar:read, polar:write |
Questions
Section titled “Questions”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.
Can an admin API key create another key?
Section titled “Can an admin API key create another key?”No. Keys are created in the Console by an organization owner.
What happens if a key leaks?
Section titled “What happens if a key leaks?”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.