Documentation

Updated

For AI agents

This page is for agents, and for people who point an agent at algizian. It lists the machine-readable entry points, what an agent can do with each and the rules to follow.

Entry points

WhatWhere
Site summary for language modelshttps://algizian.com/llms.txt
Management API, OpenAPI 3.1https://id.algizian.com/api/v1/openapi.json
Management MCP serverhttps://id.algizian.com/mcp (Streamable HTTP, bearer token)
A tenant's OpenID configurationhttps://<slug>.algizian.com/.well-known/openid-configuration
A tenant's OAuth authorization server metadatahttps://<slug>.algizian.com/.well-known/oauth-authorization-server
A tenant's public keyshttps://<slug>.algizian.com/jwks.json

The documentation pages are plain HTML with no scripts needed to read them: quick start, concepts, management API, MCP, custom domains and your own provider apps.

What an agent can do

  • Set up a tenant: create it, set its branding, add clients, add a custom domain and read back the DNS record to create. Over REST or over MCP; the operations are the same.
  • Look after users: list the users of a tenant, find one by email, block or unblock them, delete them.
  • Check configuration: read a tenant's discovery document and key set to confirm what a client will see.
  • Verify tokens: validate an access or ID token with the tenant's key set. No call to algizian is needed for each token.

Credentials

  • Management calls need a bearer token that starts with ag_. Tokens have a scope: platform, manage (one tenant) or read (one tenant, no changes). Give an agent the narrowest token that does its job; for a single tenant that is a manage or read token.
  • Treat tokens, client secrets and refresh tokens as secrets. Keep them out of prompts, logs, repositories and chat transcripts. A secret is returned once, at creation, and cannot be shown again.
  • Sign-in itself is for people: a user always signs in with Google, Microsoft or Apple. An agent never needs a person's provider password and algizian has no passwords to give.

Rules for acting for someone

  1. Do only what the person asked. Deleting a tenant, a client or a user, rotating keys, removing a domain and revoking a token cannot be undone or break running apps; confirm those with the person first.
  2. Prefer read calls to inspect before you change anything, and report the result of each change in plain words.
  3. Do not create tenants, clients or domains speculatively. Tenant names within a reserved list, other brands' domains and shared hosting domains are refused.
  4. Do not store or log users' personal data (email, name, picture) beyond what the task needs.
  5. Respect errors. Problem responses say what is wrong; fix the input rather than retrying blindly. A 403 means the token scope does not allow the call; ask for a different token, do not work around it.

Connectors

To let a Claude or ChatGPT connector sign users in to your own MCP server, point it at a tenant as its authorization server. The steps, including dynamic client registration, are on the MCP page.