Authentication

Every /v1/* endpoint requires a bearer key, except the key-management endpoints (which use a dashboard session) and the two usage endpoints (which accept either).


curl https://api.regsn.app/v1/snapshots \
  -H "Authorization: Bearer $REGSN_API_KEY"

Key format

Property	Value
Shape	`regsn_live_` + 32 base62 characters (`A–Z a–z 0–9`)
Example	`regsn_live_aBcD1234eFgH5678iJkL9012mNoP3456`
Header	`Authorization: Bearer regsn_live_…`
Storage	SHA-256 hash only; the raw key is never stored
Masked display	first 4 entropy characters, e.g. `regsn_live_aBcD…`

Keys are account-scoped: every scan, snapshot, and export a key touches belongs to the account that created it. A key never sees another account’s data.

Never put a key in a URL. Always use the Authorization header — keys in URLs end up in browser history, access logs, and referrers. Treat a key like a password: environment variables or a secrets manager, not source control.

Where keys come from

Keys are created and managed in the developer dashboard at api.regsn.app — sign in with your regsn.app account. The dashboard shows plan, usage, and every key with its masked prefix, creation date, and last-used time.

The raw key is returned exactly once, at creation. Copy it then.
You can hold up to 10 active keys at a time. Revoke one to make room.
last_used_at updates as a key is used (at most once every 60 seconds), so you can spot dormant keys before revoking them.
Revocation takes effect immediately: revoked keys receive 401 with code key_revoked.

Rotation is revoke-and-replace: create the new key, deploy it, then revoke the old one. Revocation is permanent — there is no un-revoke.

Authentication errors

All are 401 with an RFC 9457 problem body:

`code`	Meaning
`authentication_required`	No `Authorization: Bearer …` header.
`authentication_invalid`	Token malformed (not `regsn_live_` + 32 base62) or not recognised.
`key_revoked`	The key matched but has been revoked.


{
  "type": "https://api.regsn.app/problems/auth",
  "title": "Authentication failed",
  "status": 401,
  "detail": "This key has been revoked. Create a new key at api.regsn.app.",
  "instance": "/v1/snapshots",
  "code": "key_revoked",
  "request_id": "req_m3k9…",
  "errors": []
}

Key-management endpoints

The dashboard drives these three endpoints. They authenticate with a signed-in dashboard session (a Clerk session token), never with a bearer key — a regsn_live_… key cannot create or revoke keys. They are rate-limited to 10 requests/minute per user.

For most integrations you never call these directly — use the dashboard. They are documented for completeness and for teams automating key issue from a session-holding context.

Create a key

POST /v1/keys

Body field	Type	Required	Constraints
`name`	string	yes	1–64 characters: letters, digits, space, `- _ . ( )`


curl https://api.regsn.app/v1/keys \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-backend" }'

201:


{
  "id": "3f2c…",
  "name": "production-backend",
  "key": "regsn_live_aBcD1234eFgH5678iJkL9012mNoP3456",
  "key_prefix": "regsn_live_aBcD…",
  "created_at": "2026-07-20T09:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "project_id": null
}

key is present only in this response. Errors: 422 validation_error (bad name), 422 key_limit_exceeded (already 10 active keys).

List keys

GET /v1/keys — returns every key for the account, newest first, masked:


{
  "data": [
    {
      "id": "3f2c…",
      "name": "production-backend",
      "key_prefix": "regsn_live_aBcD…",
      "created_at": "2026-07-20T09:00:00.000Z",
      "last_used_at": "2026-07-20T11:41:00.000Z",
      "revoked_at": null,
      "project_id": null
    }
  ]
}

Revoke a key

POST /v1/keys/{id}/revoke — idempotent; revoking an already-revoked key returns the original revoked_at.


{ "id": "3f2c…", "revoked_at": "2026-07-20T12:00:00.000Z" }

404 not_found if the key id does not exist on your account.

Dual authentication on `/v1/usage`

GET /v1/usage and GET /v1/usage/budget accept either a bearer key or a dashboard session, so the same endpoint serves SDK clients and the dashboard. Routing is by token shape: tokens starting regsn_live_ take the bearer path; anything else is treated as a session token.