API keys
Every request carries an API key as a bearer token:
Authorization: Bearer sc_live_...A key belongs to one workspace: every job, webhook and view link it makes is that workspace’s, and another workspace’s ids answer exactly as missing ones do.
Getting a key
Section titled “Getting a key”A workspace’s owner or an admin makes keys in the SpecCapture dashboard, under API keys; nobody else is involved:
- Create an API key, and name it after what will use it (“ERP import”). If nobody in the workspace has yet confirmed that it takes no export-controlled drawings, the same dialog asks for it, once (Not for export-controlled drawings).
- The whole key (
sc_live_...) is shown once, with a copy button. Copy it then: SpecCapture keeps only a fingerprint of it, and once the dialog is closed the list shows just its first characters (sc_live_Ab12…). - Send it as
Authorization: Bearer sc_live_.... The screen’s “Using a key” panel gives one request to copy.
The list shows each key’s name, who made it and when, when it was last used, the role it acts with, and whether it
still works. Revoke stops a key from its very next request (401 api_key_invalid); revoked keys stay listed
below the working ones, so a stopped integration can be explained. Keys made on the screen are live keys allowed
60 requests a minute (Rate limits). A member
of the workspace sees no keys, and is told whom to ask.
The same list is in the API, read-only: GET /v1/api-keys lists the workspace’s keys newest first, a page at a time
(Lists and paging), and GET /v1/api-keys/{keyId} reads one. Each has its name, prefix (its
first characters), mode (live or test), the role it acts with, requestsPerMinute, createdBy, createdAt,
lastUsedAt, and its status: active, stopping (revoked with a grace period; it works until stopsAt) or
revoked. Never a key itself, which nothing but the dialog that made it ever shows. Reading them takes a key acting
as the owner or an admin - the people who see them in the dashboard - and making and revoking them stays in the
dashboard.
Keep a key out of code and out of source control: read it from an environment variable or a secret store, as
every sample in these docs does (SPECCAPTURE_API_KEY).
When a key is refused
Section titled “When a key is refused”| Failure | Status | Code |
|---|---|---|
No Authorization header |
401 | api_key_missing |
Not Bearer sc_live_… or Bearer sc_test_… |
401 | api_key_malformed |
| Unknown, revoked or expired - one answer for all three, on purpose - including a key revoked while its request was being handled | 401 | api_key_invalid |
| Too many keys SpecCapture does not know, from one network address in one minute | 429 | rate_limited |
| A test key used to change live configuration, such as webhooks | 403 | live_key_required |
A key whose role does not allow the action; the problem’s keyRole names the role |
403 | role_not_allowed |
Who a key acts as
Section titled “Who a key acts as”A workspace’s people are its owner, its admins and its members. A request is made by a key, not a person, so
a key acts with the role the person who created it had when they created it: demoting or removing that person
later does not quietly break an integration (revoking the key stops it). Only an owner or an admin can create a
key, so every key acts as one of those; a key made before keys had roles acts as a member until it is replaced.
GET /v1/account names the role a key acts with (apiKey.role).
| Action | An owner’s or admin’s key | A member’s key |
|---|---|---|
| Submit, read and export extractions; read the account, the workspace and its people; list webhooks and their deliveries | yes | yes |
| Add or delete a webhook endpoint | yes | 403 role_not_allowed |
| Make, list, read or withdraw a read-only view link | yes | 403 role_not_allowed |
| List and read the workspace’s API keys - never a key | yes | 403 role_not_allowed |
| List and read the workspace’s open invitations - never a link | yes | 403 role_not_allowed |
| Manage people, invitations, roles or API keys, or delete the workspace | in the dashboard only | in the dashboard only |
Live and test keys
Section titled “Live and test keys”A live key (sc_live_...) reads drawings and spends credits. A test key (sc_test_...) will never spend
credits or read a drawing: it will replay the sample gallery’s results, so an integration can be built at no
cost. That replay is not open yet, so today a test key answers every extraction request with
501 test_mode_not_available, cannot change live configuration such as webhooks or view links
(403 live_key_required), and works for GET /v1/account.