Account API keys

Authalla exposes two REST APIs, each with the credential that fits its job. The Application API is the data plane—a tenant-bound credential your backend uses to manage users at runtime. The Management API is the control plane—an account-wide credential an operator uses to provision and configure identity infrastructure: tenants, OAuth2 clients, custom domains, custom emails, social logins, and themes.

An account API key is the credential for the Management API. It is a single opaque bearer token you create in the dashboard, drop into a CI secret or a curl call, and use to manage everything across your account—no OAuth flow, no token refresh, no per-tenant credential juggling.

Two APIs, two credentials

The two surfaces never overlap—no resource is exposed on both. Pick the API by what you are doing, and the credential follows.

If you are integrating an application to manage users at runtime, use the Application API with your tenant's client-credentials token. If you are provisioning the account itself, read on.

Create a key

Account API keys live in the dashboard under Settings → API Keys, alongside your other account-level settings. Only account owners and admins can create or revoke them.

1. Open Settings → API Keys and click Create API key.
2. Give the key a name (e.g. terraform-prod, ci-provisioning) so you can tell your keys apart later.
3. Choose its scopes—either a preset or an explicit set (see Scopes).
4. Choose its tenant access—account-wide or a specific allowlist (see Tenant access).
5. Optionally set an expiry so short-lived automation credentials self-retire.
6. Click create. The full key is shown exactly once.

The key looks like this:

authalla_ak_<keyid>_<secret>

Copy it immediately and store it in your secret manager. Authalla stores only a hash—the value is never recoverable afterward. If you lose it, revoke the key and create a new one.

Authenticate

Send the key as a bearer token on every Management API request:

curl https://api.authalla.com/management/v1/tenants \
  -H "Authorization: Bearer authalla_ak_<keyid>_<secret>"

Authalla looks the key up by its id, verifies the secret with a constant-time compare, rejects it if it is revoked or expired, and stamps its last-used time. There is no token endpoint and no refresh step for the Management API.

Hierarchical, tenant-explicit paths

Every Management API operation names the tenant it acts on directly in the URL, so there is never any ambiguity about which tenant a request touches:

GET    /management/v1/tenants
POST   /management/v1/tenants
GET    /management/v1/tenants/{tenant_id}/clients
POST   /management/v1/tenants/{tenant_id}/clients
PUT    /management/v1/tenants/{tenant_id}/theme
GET    /management/v1/tenants/{tenant_id}/domains

Account-level operations (listing, creating, and deleting tenants) live at the collection root /management/v1/tenants. Tenant-scoped resources—clients, domains, emails, social logins, and theme—live under /management/v1/tenants/{tenant_id}/….

Every resource supports the full create / read-by-id / update / delete / list set with stable IDs, so the API is ready to drive a Terraform provider. See the Management API reference for the complete endpoint list and schemas.

Scopes

Keys carry an explicit set of scopes, so a key only does what it is meant to. The vocabulary is uniform resource:read / resource:write:

• account:read (read-only—there is no account:write)
• tenants:read / tenants:write
• clients:read / clients:write
• domains:read / domains:write
• emails:read / emails:write
• social-logins:read / social-logins:write
• theme:read / theme:write

Two presets make the common cases one click:

• Full access grants every scope—a broad provisioning key.
• Read-only grants every :read scope and nothing else—ideal for an audit key, a Terraform plan, or drift detection that must never mutate anything.

A request that exceeds a key's scopes is rejected, so the privilege boundary is enforced by the server, not just by convention.

Tenant access

Each key has a tenant mode:

• Account-wide — the key can act on every tenant in the account, including tenants created later. This is what a Terraform provisioning key wants: it can create a tenant and immediately configure it.
• Specific tenants — the key is restricted to an explicit allowlist. Hand a team a key that only touches their tenant(s); a request for any other tenant is rejected.

Because creating a tenant would place it outside an allowlist, account-collection tenant operations (creating, listing, and deleting tenants at /management/v1/tenants) are honored only on account-wide keys. An allowlisted key cannot create tenants.

Security

Account API keys are high-blast-radius by nature, so they are designed to be locked down:

• Hashed at rest. Only a hash is stored; a database disclosure never leaks a usable credential.
• Shown once. The full value appears only at creation and is never recoverable afterward.
• Scoped and tenant-restricted. Grant least privilege from day one—read-only keys and single-tenant keys are first-class.
• Revocable. Revoke a key and it stops working immediately. Rotation is revoke-and-recreate: issue a new key, cut over, then revoke the old one.
• Optional expiry. Short-lived automation credentials self-retire.
• Owner/admin only. Only account owners and admins can issue or revoke keys.
• Audited. Every Management API action is attributed to the specific key in your audit log, so you can always trace which key did what.

The Application API is users-only

Because the control plane now has its own credential, the Application API is narrowed to its real job: managing users within a single tenant. A tenant client-credentials token can no longer request or use management scopes (tenants:*, clients:*, and the rest)—those requests are rejected. The credential's level now matches the operation's level.

See the Application API for the runtime user operations available to a tenant credential, and the Management API reference for everything an account API key can do.