Authentication
Bearer token
Send Authorization: Bearer sk_live_… on every request. Never put a key in a URL or a cookie; there is no other header for it. A missing, malformed, revoked or expired key answers 401 unauthorized, with no hint which.
A key belongs to one workspace. GET /v1/workspaces/current returns it and its plan. If you send X-Workspace-Id, it must name the key's workspace.
Creating keys
Create keys in the app under Settings → API. Editors, admins and the owner create keys that act as themselves; admins can also rename and revoke anyone's. Viewers can't create keys. A workspace can hold 50 live keys.
The secret is shown once and we keep only its hash. The API doesn't allow cross-origin browser calls: keep keys on your server.
Scopes
Pick scopes when you create the key; they can't be changed afterwards (roll or create a new key instead). A request needs the route's scope, listed next to every route in the API reference. A key without it gets 403 forbidden with details.reason missing_scope.
codes:readList and read codes, their versions and activity; download files; start and read exports and bulk runs.Viewer or abovecodes:writeCreate, change, pause, move and delete codes; bulk create; upload logos and files.Editor or aboveanalytics:readWorkspace and per-code analytics, and per-scan records.Viewer or abovesubmissions:readAnswers to hosted forms. They hold respondents' personal data.Editor or abovefolders:readList and read folders.Viewer or abovefolders:writeCreate, rename, move and delete folders. Sharing stays in the app.Editor or abovetemplates:readList and read design templates.Viewer or abovetemplates:writeCreate, change and delete design templates.Editor or abovedomains:readList custom domains and their status, to pick one for new codes.Viewer or abovewebhooks:readList webhook endpoints and their deliveries.Admin or abovewebhooks:writeRegister, change and delete webhook endpoints; send a test event; redeliver. Admins only.Admin or abovetags:readList workspace tags and how many codes carry each.Viewer or abovetags:writeCreate, rename, recolour and delete tags. Tagging codes needs Codes · write.Editor or abovecards:readList and read team business cards and their analytics.Viewer or abovecards:writeCreate, change, deactivate and reassign business cards. Admins only.Admin or aboveconversions:writeSend conversions from your server (orders, sign-ups) for the scan funnel.Editor or aboveRoles
A key never does more than its creator's current role allows, capped at Editor. If the creator is demoted to Viewer, the key loses its write scopes at once; when the creator leaves the workspace, their keys are revoked.
webhooks:read and webhooks:write are the exception: only admins and the owner can grant them, and they keep working only while the creator is still an admin.
Folder and IP restrictions
A key can be limited to up to 20 folders and their subfolders — one key per client folder, for instance. It then sees nothing outside them, and a write elsewhere answers 403 with details.reason api_key_folder_restricted.
A key can also be limited to up to 20 IP ranges in CIDR form (203.0.113.0/24). A call from anywhere else answers 403 with details.reason ip_not_allowed.
Expiry and rolling
A key can expire on a date you pick. Rolling a key issues a new secret with the same name, scopes and restrictions; the old secret keeps working for 24 hours by default (0 to 168), so you can deploy the new one without downtime. Revoking takes effect immediately.
What a key can't do
Keys call only the routes in the API reference. Your account, members and invites, billing, workspace settings, sharing, domain setup and API keys themselves stay in the app: those routes answer a key with 403 forbidden and details.reason session_required.