Management API
Everything the dashboard does, it does through the management API, and so can your scripts and CI: create apps, configure environments, clients, APIs and roles, look users and sessions up, manage webhooks and domains.
- Base URL:
https://api.auth.dev.seek.services/v1 - Bodies: JSON in, JSON out. Times are RFC 3339 strings, ids are UUIDs.
- Errors:
{ "code", "message" }with the HTTP status.
Authentication
Section titled “Authentication”API keys
Section titled “API keys”An API key is how a script or a CI job calls the API. Admins and owners create them in the dashboard (Workspace → API keys) or with POST /v1/workspaces/:id/api-keys, and each one is made for one kind of environment:
| Key | Prefix | Reaches |
|---|---|---|
| Development | sk_dev_ |
The workspace’s apps and groups to read, and its development environments. |
| Production | sk_live_ |
The workspace’s apps, groups, usage and billing to read, and its production environments. |
Send it as a bearer token:
curl https://api.auth.dev.seek.services/v1/environments/$ENVIRONMENT_ID \ -H "Authorization: Bearer sk_dev_..."What a key may do:
- It acts in one workspace, with the developer role. Another workspace, and an environment of the other kind, answer
404. - At the workspace’s level it only reads: creating an app or adding one to a group answers
403, since an app has an environment of each kind. A development key also gets403for the workspace’s usage and billing, which count production. No key is shown who pays (customer_email). - It cannot do what only people may: read
/v1/me, create or revoke API keys, or send and answer invitations (403). Routes that need the admin or owner role answer403as well.
The key itself is shown once, in the answer that creates it; SeekAuth keeps only its SHA-256 hash. A key has no expiry. It stops working when it is revoked, when the person who made it leaves the workspace or drops below admin (their keys are revoked with it), and while their account is disabled. To rotate a key, create a new one and revoke the old one. Every action taken with a key names it (api_key_id) in the audit log.
Dashboard sessions
Section titled “Dashboard sessions”The dashboard calls the same API with its signed-in developer’s access token: a DPoP-bound token of the dashboard client for the management-api audience, from a login with two steps (acr aal2). A token without a second factor answers 401 step_up_required. Nothing else may use these tokens; for automation, use an API key.
A workspace’s members each have one role. Every route needs at least one of them:
| Role | May |
|---|---|
viewer |
Read everything in the workspace. |
developer |
Also create apps, change environments’ settings, clients, APIs, roles, users’ standing, which events a webhook endpoint gets, delete an endpoint, end a session. This is an API key’s role. |
admin |
Also everything that lets more people in or reaches every user: members and invitations, API keys, opening an app’s access, custom domains and moving the issuer, ending every session, token and session lifetimes, client secrets and machine-client roles, webhook endpoints’ addresses and secrets, renaming apps and groups. |
owner |
Also billing, deleting a group, and granting or taking away the owner role. |
A workspace you have no role in answers 404, as if it did not exist; a role too weak for the route answers 403. A workspace always keeps one owner: removing or demoting the last one answers 409.
Pagination
Section titled “Pagination”Lists that can be long take a cursor and a limit, and answer the cursor of the next page, which is null once a page comes back with fewer than limit items:
| List | Cursor | Next | Order | limit |
|---|---|---|---|---|
| Sessions | before |
next_before |
Last used, newest first | 25, at most 100 |
| Audit log | before |
next_before |
Newest first | 50, at most 200 |
| Users and app users | after |
next_after |
By id | 50, at most 200 |
A limit out of range is clamped, not refused. Other lists (groups, apps, members, invitations, keys, endpoints) come whole.
Rate limits
Section titled “Rate limits”| What | Limit |
|---|---|
| Creating workspaces, per developer | 30 an hour |
| Creating apps, per workspace | 30 an hour |
| Workspaces one developer may own | 10 (then 409) |
| Invitations sent, per inviting developer | 30 an hour |
| Invitation emails to one address, across all workspaces | 5 a day (past it the invitation is made without an email) |
| Moving a group or an app on its own to another slug, per workspace | counts as creating an app (the address it leaves stays held for the workspace) |
Checking a payment (billing/confirm), per workspace |
30 an hour |
Starting a checkout that is not open already (billing/checkout), and cancelling (billing/cancel) |
10 an hour per workspace and 20 per developer, each |
| Any call, per developer, API key or service | 600 a minute and 10,000 an hour |
A string that is not shaped like an API key (sk_dev_ or sk_live_ and 43 characters), and a key that does not exist, is 401 at once and counts against nobody: no number of made-up keys, from your address or anyone’s, makes a valid key wait.
Over a limit the answer is 429 rate_limited with a Retry-After header in seconds.
Plan limits
Section titled “Plan limits”Creating something the workspace’s plan has no room for (an app group, an app in a group, a member or an invitation, a custom domain, a custom provider, a webhook endpoint) answers 402 plan_limit, with a message such as “The Free plan includes 1 app with accounts of its own. The Pro plan includes more.” On Scale, which has no larger plan on sale, the same answers 409. A workspace over a limit because its plan shrank keeps what it has. See Plans and limits.
The API answers cross-origin requests only from the dashboard. Call it from a server, a script or CI, never from your own web pages: an API key is a secret.
Sections
Section titled “Sections”| Page | Routes |
|---|---|
| Workspaces and members | /v1/me, workspaces, members, invitations, API keys, usage |
| Apps and groups | apps, app groups, slugs, an app’s users |
| Environments | an environment’s settings, security policy, login methods, providers, appearance, signing keys |
| Clients | clients, secrets, a client’s APIs and roles |
| APIs and roles | APIs, permissions, roles |
| Users | users, their roles, ending their sessions |
| Sessions and lifetimes | sessions, ending one or all, lifetimes |
| Webhooks | endpoints, secrets, deliveries |
| Domains | custom domains, the issuer |
| Audit log and analytics | the audit log, analytics, the live view |
| Billing | plans, the workspace’s plan, checkout, cancellation |