Updated
Management API
The management API is a JSON REST API for everything you configure in algizian: tenants, OAuth clients, branding, custom domains, signing keys, tenant tokens and users. There is no dashboard; this API and the MCP server are the control surface.
- Base address:
https://id.algizian.com/api/v1 - OpenAPI 3.1 document: https://id.algizian.com/api/v1/openapi.json
- Errors:
application/problem+json(RFC 9457) withtitle,detailand, for invalid input, the list of offending fields. - Responses are never cached.
Authentication and scopes
Send a bearer token on every request. Tokens start with ag_ and are shown only once, when they are created.
curl -s https://id.algizian.com/api/v1/me -H "Authorization: Bearer $ALGIZIAN_TOKEN"
| Scope | What it can do |
|---|---|
platform | Everything, on every tenant: create and delete tenants, create and revoke tenant tokens. |
manage | Read and change one tenant: its branding, providers, domain, clients, keys and users. |
read | Read one tenant. No changes. |
A platform token creates manage and read tokens for a tenant, so you can hand a narrow token to a deployment pipeline or an agent. GET /me tells you the scope and the tenant of the token you are using.
Resources
| Resource | Calls |
|---|---|
| Tenants | POST /tenants, GET /tenants, GET /tenants/{tenant}, PATCH /tenants/{tenant}, DELETE /tenants/{tenant} |
| Custom domain | PUT /tenants/{tenant}/domain, POST /tenants/{tenant}/domain/refresh, DELETE /tenants/{tenant}/domain |
| Sign-in providers | GET /providers, GET /providers/{provider}/setup (registration guide), GET /tenants/{tenant}/providers, PUT and DELETE /tenants/{tenant}/providers/{provider}/credentials |
| Clients | POST /tenants/{tenant}/clients, GET /tenants/{tenant}/clients, GET, PATCH and DELETE /tenants/{tenant}/clients/{id} |
| Signing keys | GET /tenants/{tenant}/keys, POST /tenants/{tenant}/keys/rotate |
| Tenant tokens | POST /tenants/{tenant}/tokens, GET /tenants/{tenant}/tokens, DELETE /tenants/{tenant}/tokens/{id} (platform scope) |
| Users | POST /tenants/{tenant}/users, GET /tenants/{tenant}/users, GET /tenants/{tenant}/users/{id}, POST .../block, POST .../unblock, DELETE .../users/{id}, DELETE .../users/{id}/identities/{identityId} |
{tenant} is the tenant slug.
Tenants
Create a tenant (platform scope). Only slug is required.
curl -s -X POST https://id.algizian.com/api/v1/tenants \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "acme-games",
"name": "Acme Games",
"providers": ["google", "microsoft", "apple"],
"branding": { "displayName": "Acme Games", "primaryColor": "#c2410c" }
}'
{
"slug": "acme-games",
"name": "Acme Games",
"issuer": "https://acme-games.algizian.com",
"branding": { "displayName": "Acme Games", "primaryColor": "#c2410c" },
"providers": ["google", "microsoft", "apple"],
"createdAt": "2026-11-21T08:05:00.000Z"
}
The answer to a create also carries a notice with the wording to pass on to the tenant: while it uses the shared provider apps, its users should be told that it uses the Algizian authentication server for social sign-in. A taken slug returns 409; an invalid or reserved slug returns 400. PATCH changes name, branding and providers. DELETE removes the tenant and all of its clients, users, sessions and tokens, and cannot be undone.
Branding
Branding applies to the sign-in and consent screens of the tenant. Set it when creating the tenant or later with PATCH. In a PATCH, a field set to null is cleared and a field you leave out is unchanged.
| Field | Meaning |
|---|---|
displayName | Name shown on the screens, up to 80 characters |
logo | Read only: the uploaded logo, { key, width, height }. Set it with the logo endpoint below, never with PATCH |
primaryColor, backgroundColor, textColor | Colours as #rrggbb |
signInTitle | Heading of the sign-in screen, up to 80 characters |
signInSubtitle | Line below the heading, up to 200 characters |
consentNote | Extra text on the consent screen, up to 300 characters |
footerText | Footer text, up to 200 characters |
sharedAppNotice | Replaces the line under the provider buttons that says Algizian provides the sign-in (shown only while a provider uses the shared apps), up to 300 characters, see what your users will see |
curl -s -X PATCH https://id.algizian.com/api/v1/tenants/acme-games \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "branding": { "signInTitle": "Welcome back", "footerText": null } }'
Custom CSS and templates are not supported.
Logo
Upload the logo as the raw image file; algizian re-renders it, so every tenant logo looks the same size and shape.
curl -s -X PUT https://id.algizian.com/api/v1/tenants/acme-games/branding/logo \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: image/png" \
--data-binary @logo.png
DELETE /tenants/{tenant}/branding/logo removes it. The answer is the tenant with branding.logo. What is accepted and what happens to the image:
- Formats: PNG, JPEG and WebP, recognised from the file itself, not from the
Content-Typeheader. SVG, GIF, animated images and anything else are refused. - Size: at most 1 MB. The shorter side must be at least 128 pixels and neither side may be longer than 2048 pixels. Each refusal is a
400problem that says why, so you can fix the file and try again. - Shape: the logo is always square. A wide or tall image is not refused: it is scaled until it fills the square and the overflow is cut off evenly (left and right, or top and bottom). Put the important part in the middle.
- Result: a 128 x 128 pixel image with all metadata removed, shown at 64 x 64 on the sign-in, consent and linking screens in a fixed frame, with the sign-in host written under it. Images are only ever scaled down, never enlarged.
- Replacing or deleting removes the previous file; deleting the tenant removes it too.
- While logo upload is not available on the server, the endpoint answers
503and the screens work as before.
Custom domain
PUT /tenants/{tenant}/domain with { "hostname": "login.example.com" } registers a domain and returns the DNS record to create. The custom domains page walks through it.
Clients
curl -s -X POST https://id.algizian.com/api/v1/tenants/acme-games/clients \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme web app", "redirectUris": ["https://app.example.com/callback"] }'
| Field | Meaning |
|---|---|
name | Shown on the consent screen, up to 80 characters |
redirectUris | 1 to 20 addresses, matched exactly. https, http on localhost, 127.0.0.1 or [::1], or a reverse-domain scheme such as com.example.app. No wildcards |
type | public (default, uses PKCE) or confidential (gets a clientSecret, shown once) |
firstParty | true (default) skips the consent screen |
grantTypes | authorization_code and refresh_token (both by default) |
The answer carries the client id, which is the client_id in the sign-in flow.
Your own provider apps
By default sign-ins use the shared Google, Microsoft and Apple apps, so the consent screen names algizian. To show your own name, register your own app with the provider (step by step in Your own provider apps) and give algizian its credentials:
curl -s -X PUT https://id.algizian.com/api/v1/tenants/acme-games/providers/google/credentials \
-H "Authorization: Bearer $ALGIZIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "clientId": "123456-example.apps.googleusercontent.com", "clientSecret": "..." }'
google and microsoft take clientId and clientSecret; apple takes clientId (the Services ID), teamId, keyId and privateKey (the contents of the .p8 file) and optionally domainAssociation (Apple's domain verification file, served on your hosts). The secret is stored encrypted and is never returned. The answer lists the redirect URIs to register in the provider's console (your sign-in host, plus the custom domain when active) and a warning that your users' provider account ids change (see the guide). GET /tenants/{tenant}/providers lists each provider with its source (shared or own) and client id. DELETE .../providers/{provider}/credentials goes back to the shared app. Writing needs a manage or platform token.
Signing keys
Every tenant has its own signing keys; their public parts are the tenant's key set at /jwks.json. POST /tenants/{tenant}/keys/rotate creates a new key for new tokens and keeps the old one published for 7 days, longer than any token lives, so tokens issued before the rotation still verify.
Tenant tokens
With a platform token, POST /tenants/{tenant}/tokens with { "name": "ci", "scope": "manage" } (or read) returns a token for that tenant. The secret is shown once; later calls list only a prefix. DELETE revokes a token.
Users
Users appear when someone signs in, or you can create one first with POST /tenants/{tenant}/users to import people from another system. The body can carry id (it becomes the user's sub), email, emailVerified, name, status and identities, a list of { provider, subject } that a later sign-in matches exactly. Without an identity, a later sign-in with the same verified email links to the user, which needs emailVerified: true on import. A duplicate id, verified email or identity answers 409. List users with GET /tenants/{tenant}/users, filtered with email or status (active or blocked) and paged with limit (up to 200) and after. The answer carries next when there are more pages.
curl -s "https://id.algizian.com/api/v1/tenants/acme-games/users?status=active&limit=20" \
-H "Authorization: Bearer $ALGIZIAN_TOKEN"
GET .../users/{id} adds the linked provider accounts. POST .../block refuses further sign-ins and ends the user's sessions and refresh tokens at once; POST .../unblock reverses it. DELETE .../users/{id}/identities/{identityId} unlinks one provider account from the user (404 if it is not theirs, 409 if it is their last one, since they could no longer sign in). DELETE removes the user, their linked accounts, sessions and refresh tokens; the person can later sign up again as a new user.
Not available yet
Invitations and allow lists, custom CSS or templates, and infrastructure-as-code providers are not part of the API today.