Skip to content

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.

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:

Terminal window
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 gets 403 for 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 answer 403 as 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.

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.

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.

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.

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.

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