Developer portal & API keys
AxisSynapse ships a public developer portal where developers can read the OpenAPI surface, browse webhook events, look up error and audit codes, and exercise the API in a signed-in playground without leaving the docs. Workspace-scoped API keys ride alongside the account-scoped Personal Access Tokens, SCIM tokens, and webhook signing secrets. This page covers when each flavor of credential is the right choice, how the developer portal fits the docs site, and the rotation discipline that keeps secrets fresh.
TL;DR — Push public developer reading to the docs site (
/reference/api,/reference/events,/reference/errors,/reference/audit-actions). Use PATs for ad-hoc scripts, SCIM tokens for directory sync, webhook signing secrets for outbound events, workspace API keys for production-scale backend integrations. Every credential is shown once, scoped, rotatable, and step-up-protected on elevation.
Where to send developers
| Field | What it does | Accepted values / default |
|---|---|---|
| API reference | Every public endpoint, its request shape, its response shape, the error codes it returns. | /reference/api on docs.axissynapse.com. Generated from the canonical registry — never drifts from code. |
| Webhook event catalogue | Every event type, payload shape, severity, suggested filter glob. | /reference/events. Cross-links to the platform / webhook subscription surface. |
| Error catalogue | Every public error code, its HTTP status, its remedy. | /reference/errors. Surfaced inline at the end of every doc page that can produce errors. |
| Audit code catalogue | Every audit-action code, its category, its severity. | /reference/audit-actions. Print-perfect for SOX / SOC 2 evidence. |
| OpenAPI download | Machine-readable spec for code generation. | Downloadable from /reference/api. OpenAPI 3.1. |
| Webhook signature verifier | Browser-side HMAC verifier. | /reference/api → playground. Validates a body + signature against your subscription's secret. |
Choose the right credential
| Field | What it does | Accepted values / default |
|---|---|---|
| Personal Access Token (PAT) | An account-scoped, long-lived bearer token used by scripts you run as yourself. | Best for: small integrations, ad-hoc reporting, single-developer automation. See /account/personal-access-tokens. |
| Workspace API key | A workspace-scoped bearer token used by production backends. Not bound to any single user. | Best for: production-scale automation. Survives team changes. Rotatable on a schedule. |
| SCIM bearer token | Authenticates your identity provider's SCIM connector. | Best for: directory sync. One per workspace; rotate when the IdP integration is reconfigured. |
| Webhook signing secret | Shared secret used to compute HMAC signatures on outbound deliveries. | One per subscription. Rotate periodically; rotation is step-up-protected. |
Create a workspace API key
Open Settings → Developer → API keys
The page lists existing keys with their label, scopes, last-used timestamp, and rotation status.
Click "Generate API key"
A drawer asks for a Label, the Scope set, and an optional Expiry.
Pick the scopes
Scopes are the customer-facing names from the OpenAPI surface (e.g.
platform:read,hcm:write). The drawer groups scopes by module and surfaces a "read-only" preset for quick selection.Set an expiry (optional but recommended)
Pick from No expiry, 90 days, 180 days, 365 days, or a custom date. Production keys should have an expiry — it forces a rotation cadence.
Complete the step-up prompt
Key creation requires a fresh MFA proof.
Copy the key once
The key value is shown ONCE. Paste it into your production secret store immediately; it cannot be retrieved again.
Rotate a workspace API key
Click the key's row → Rotate
A drawer asks for the Overlap period — how long the old and new keys both authenticate.
Pick an overlap period
Default 24 hours. Long enough that your production system can pick up the new key, short enough that the old key isn't a long-tail risk.
Copy the new key
Shown once. Update your secret store; deploy the new value to every consumer of the key.
Verify all consumers switched
The key's row shows a real-time "last used (old)" and "last used (new)" timestamp. When the old timestamp stops advancing, every consumer is on the new key.
The old key auto-expires after the overlap
No manual cleanup. The overlap is a one-shot mechanism per rotation.
Every field, explained
| Field | What it does | Accepted values / default |
|---|---|---|
| Label | Free-text identifier for the key. | Up to 100 characters. Used in audit lines for context. |
| Scope set | Which API surfaces the key can access. | One or more module + read/write scope strings. Visible in the playground. |
| Expiry | When the key auto-revokes. | No expiry / 90d / 180d / 365d / custom. Production keys should set one. |
| Overlap period (rotation) | How long the old key remains valid alongside the new one. | 1-72 hours. Default 24h. |
| Last used (old / new) | Timestamps showing rotation completion. | Read-only. Drives the 'all consumers switched' signal. |
| Step-up on elevation | Increasing a key's scope past read-only. | Step-up protected. Read-only → read/write is a separate operation, audited. |
What appears in the audit log
Workspace API key lifecycle emits dedicated codes; the most sensitive operations also require step-up (see Step-up authentication).
- Lifecycle of API keys, PATs, and SCIM tokens appear in Security Console under the API filter.
- Webhook signing secret rotation appears under the Webhooks filter.
- Personal access token operations (issuance, scope change,
revocation) emit
ACCOUNT_PAT_CREATED/ACCOUNT_PAT_REVOKED.
Common gotchas
- "I lost the API key." Cannot be retrieved. Rotate the key (which generates a new value) and update consumers. The old key remains valid for the overlap period; cancel the rotation if you realize the loss before overlap ends.
- "My production system kept the old key after rotation." Watch the last used (old) timestamp. If it keeps advancing past the overlap window, a consumer wasn't redeployed.
- "I want to limit a key to one IP." API keys don't enforce IP binding; rely on the workspace network policy for IP-level scoping.
- "A PAT and an API key with overlapping scopes both exist — which one wins?" Neither overrides the other; both can access the same resources. Decide intentionally which credential type each consumer uses.
- "The OpenAPI download didn't include a new endpoint." The
surface is generated; check the deploy timestamp in
/reference/api. New endpoints land with each platform release.
Troubleshooting
| Error code | What it means | Fix |
|---|---|---|
| API_KEY_INVALID | The bearer token is unknown or expired. | Use a current key. |
| API_KEY_SCOPE_INSUFFICIENT | The endpoint requires a scope the key doesn't carry. | Rotate to a key with the needed scope. |
| API_KEY_EXPIRED | The key reached its expiry date. | Rotate. |
| API_KEY_ROTATION_OVERLAP_ACTIVE | A second rotation was attempted before the previous overlap ended. | Wait for the overlap to elapse or cancel the in-flight rotation. |
Related