Authentication

All /v1 endpoints require an API key in the Authorization header:

To create a key or check eligibility, start with Get API access.

Authorization: Bearer YOUR_API_KEY

Keys are issued through Substy, backed by Clerk, and scoped to one agency and the user who created them. An ordinary Clerk session token, an MCP OAuth token, or an arbitrary key created outside Substy’s issuance flow is not a substitute.

Key lifecycle

Your agency role must allow Use personal API keys to create or use a key. Ask your agency owner to enable this permission if it is unavailable. Organization-owned Clerk keys are not supported.

Choose a meaningful name, expiration, agency, and category access when creating a key. The full secret is returned when it is created; store it securely. Keep separate keys for separate applications so you can revoke one without interrupting the others.

Rotate a key by creating a replacement, updating your application, verifying a request, and revoking the old key. Expired or revoked keys are rejected. Removing the issuing user’s agency membership or personal API permission also blocks existing keys, including browser continuations. You can still revoke your own keys after losing access.

Permissions remain current

The API checks current agency membership and creator permissions. Promoting a key’s category access does not promote the user’s role. See permissions for how these controls combine.

Authentication failures

A 401 response means the key is missing, invalid, expired, revoked, or cannot be authenticated. A 403 means the caller lacks access to the requested agency or action. Do not repeatedly retry either response with the same credentials.

The service health checks and /openapi.json are public. No API key is needed to browse this documentation, and this site does not ask for or store your key.