Choosing an API - Authalla Docs

Each of Authalla's REST APIs comes down to two facts: what you call it with, and whose data it reaches. The Application API, the Management API and SCIM are called from your server with a secret credential (an account API key, or a client secret and the client credentials token it gets). A secret credential reaches every user of a tenant or the whole account, so it never goes in a browser or a mobile app. The User API is called with the signed-in user's own access token, which reaches only that user, so your app may call it from the browser. Start from whose data you act on: one signed-in user's own, or the tenant's and the account's. The job then decides the API.

Decision table

You want to…	Use	Credential
Create, read, update or delete the users of your tenant from your server	Application API	Secret credential: client credentials access token
Create tenants, or configure apps, custom domains, sender addresses, social logins, resource servers or the theme	Management API	Secret credential: account API key
Keep your tenant configuration in code (CI, Terraform, scripts)	Management API	Secret credential: account API key
Sync users and groups from a customer's identity provider	SCIM	Secret credential: client credentials access token with `scim:*` scopes
Let a signed-in user change their own name, or see and end their own sessions and connected apps, in your product	User API	The user's own access token
Sign users in to your app	OAuth2 & OIDC	None: the user signs in
Let a coding agent configure Authalla for you	MCP server	None: the agent signs in with OAuth2

A user editing their own profile is a User API job, even when your server could do it with the Application API: a client credentials token can change any user of the tenant, so it must stay on your server, while the user's own token can only change that user.

At a glance

	Application API	Management API	User API
Called from	Your server	Your server, CI or Terraform	Your app, for the signed-in user
Credential	Secret credential: client credentials access token, short-lived	Secret credential: account API key, long-lived until revoked or expired	The signed-in user's own access token
Reaches	Every user of the one tenant the token belongs to	Every tenant in the account, or an allowlist	The signed-in user only
Base URL	`https://api.authalla.com/api/v1`	`https://api.authalla.com/management/v1`	`https://{tenant-id}.authalla.com/me/v1`, or your custom domain
Scopes	`users:read`, `users:write`	`resource:read` / `resource:write` per resource	`profile`, `sessions:`, `connected-apps:`
OpenAPI spec	JSON · YAML	JSON · YAML	JSON · YAML

SCIM also takes a secret credential and reaches every user of the tenant, but your customer's identity provider calls it rather than you; see SCIM provisioning.

Application API: get an access token

In the dashboard, create a Backend Service app in the tenant whose users you manage. Save the client secret: it is shown once.
Exchange the app's credentials for an access token at the tenant's token endpoint:

curl -X POST https://{tenant-id}.authalla.com/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id={client-id} \
  -d client_secret={client-secret} \
  -d scope="users:read users:write"

Call the API with the access_token from the response:

curl https://api.authalla.com/api/v1/users \
  -H "Authorization: Bearer {access-token}"

The token identifies the tenant, so no request names one. When it expires, request a new one the same way. Only client credentials tokens are accepted: a token issued to a signed-in user is rejected with 403 forbidden. See Machine-to-machine tokens for the rules.

Management API: create an account API key

In the dashboard, open Settings → API Keys and create a key. Give it only the scopes it needs, and restrict it to specific tenants if it doesn't need them all. The key is shown once.
Send it as a bearer token:

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

There is no token exchange and no refresh. Every tenant-level path names the tenant it acts on, for example /management/v1/tenants/{tenant_id}/apps. See Account API keys for scopes, tenant access and rotation.

User API: the signed-in user's own account

The User API is called from your app, not your server: it acts for the signed-in user, with their own access token, on the tenant's host (https://{tenant-id}.authalla.com/me/v1, or your custom domain; api.authalla.com doesn't serve it). It covers the user's profile, browser sessions and connected apps, and nothing of other users. Add its scopes to the app and request them at sign-in; see the User API reference.

Every API

Errors have one JSON shape, with an error code you can branch on. Every code is listed in Errors.
Changes to any of them are listed in the API changelog, newest first, with breaking changes marked.
OpenAPI specs are the source of the reference pages, and the server is tested against them. Each spec's description says what it is called with and whose data it reaches. Import them into Postman, Bruno or Insomnia, or generate a client from them.
Agents can discover the Application, Management and User API specs from https://api.authalla.com/.well-known/api-catalog, or from the Link: rel="service-desc" header on every API response.