Users and Access Reference

Every resource the gateway serves for users and access, every directive, setting and secret, and every status a client meets, with a link to where each is shown at work.

§Resources

All of these exist in every application. :identity is an identity id. “Self” means credentials of the identity in the path.

§Identity

Request	Does	Access
`GET /identity/`	Answers who the caller is; without credentials, creates a guest.	anyone
`POST /identity/`	Creates an identity for new credentials.	no identity yet
`GET /identity/credentials/:identity/`	Lists the ways to sign in.	self

§Passwords

Request	Does	Access
`POST /identity/basic/`	Creates an identity with a username and password.	no credentials
`GET /identity/basic/usernames/:username/`	Tells whether a username is taken.	no credentials
`POST /identity/basic/:identity/`	Adds a password to an identity.	self, `system:identity:basic`
`PATCH /identity/basic/:identity/`	Changes username or password.	same, with `Basic` only
`DELETE /identity/basic/:identity/`	Removes the password.	self, `system:identity:basic`

§Tokens

Request	Does	Access
`POST /identity/tokens/refresh/`	Replaces the token with one carrying current roles.	any identity, but a custom token
`POST /identity/tokens/:identity/`	Issues a custom token.	self, `system:identity:tokens`
`GET /identity/keys/:identity/`	Lists custom tokens.	self, `system:identity:keys`
`DELETE /identity/keys/:identity/:key/`	Revokes a custom token.	self, `system:identity:keys`

§Providers

Request	Does	Access
`POST /identity/federation/:identity/`	Adds a provider’s account.	self
`GET /identity/federation/:identity/`	Lists them.	self
`DELETE /identity/federation/:identity/:credential/`	Removes one.	self

§Codes and passkeys

Request	Does	Access
`POST /identity/otp/:identity/`	Issues a code for the identity.	self, `system:identity:otp`
`PUT /identity/otp/:identity/`	Ties an address to the identity with the code issued for it.	self
`POST /identity/passkeys/challenges/`	Creates a challenge; with `type: creation`, a new identity too.	no credentials
`POST /identity/passkeys/challenges/:identity/`	Creates a challenge for a known identity.	no credentials
`POST /identity/passkeys/`	Signs in with a passkey.	no credentials
`POST /identity/passkeys/:identity/`	Stores a passkey.	self
`GET /identity/passkeys/:identity/`	Lists passkeys.	self
`DELETE /identity/passkeys/:identity/:passkey/`	Removes one.	self

§Roles and bans

Request	Does	Access
`GET /identity/roles/:identity/`	Lists roles.	self, `system:identity:roles`
`POST /identity/roles/:identity/`	Grants a role.	`system:identity:roles`, `system:identity:roles:delegation`
`DELETE /identity/roles/:identity/:role/`	Revokes a role.	`system:identity:roles`
`PUT /identity/bans/:identity/`	Bans or unbans.	`system:identity:bans`

§Other applications

Served only with the oauth annotation.

Request	Does	Access
`GET /.well-known/oauth-authorization-server`	Server metadata. Also at `/.well-known/openid-configuration`.	public
`GET /.well-known/oauth-protected-resource[/path]`	Protected resource metadata.	public
`POST /identity/clients/`	Registers a client.	no credentials
`GET /identity/clients/:client/`	Describes a client.	any identity
`POST /identity/grants/:identity/`	Issues an authorization code.	self
`POST /identity/grants/`	Exchanges a code for a token.	no credentials
`GET /identity/grants/:identity/`	Lists grants.	self
`DELETE /identity/grants/:identity/:grant/`	Revokes a grant.	self

Routes marked “no credentials” refuse a request that carries valid ones with 403; see auth:anonymous.

§Operations an application calls

Call	Use
`context.remote.identity.otp.issue({ input: { authority, username, identity, lifetime } })`	Get a sign-in code to deliver to the user.

§Directives

The auth family is listed in Restrict Who Can Call a Route. Directives of other families used with it:

Directive	Use
`map:authority`	The authority of the request as an input property.
`map:claims`	Claims of a provider’s token as input properties.
`map:segments`	A route variable as an input property.
`require:header`, `require:headers`	Headers a request must carry.

§Context annotation

Keys of exposition in context.toa.yaml that concern users and access. The other keys are in Run and Configure the Gateway.

Key	Value	Default	See
`authorities`	Map of name to host. Required.		Domains
`ip`	Header that holds the client address.	none	The client address
`bouncer.attempts`	Failed sign-ins an address may make in a row.	`20`	Limit password guessing
`bouncer.interval`	Seconds in which they are earned back.	`60`
`country`	Header that holds the client’s country.	none	Refuse by country
`censor`	Countries answered `451`.
`oauth.authorize`	URL of the consent page. Required within `oauth`.		Other applications
`oauth.resources`	Paths advertised as protected resources.	none
`oauth.scopes`	Scopes advertised.	none
`oauth.registration`	`open` or `closed`.	`closed`

§Configuration

Set under configuration in context.toa.yaml, keyed by component.

Component	Key	Default	See
`identity.tokens`	`keys`	required	Keys
	`lifetime`	`2592000` s	How long a sign-in lasts
	`refresh`	`600` s
	`cache.max`, `cache.ttl`	`1024`, `600000` ms	Custom tokens
`identity.basic`	`username`, `password`	`^.{1,128}$`, `^.{8,32}$`	Rules
	`rounds`	`10`	How passwords are stored
	`pepper`	none
	`principal`	none	The first administrator
`identity.federation`	`trust`	`[]`	Providers
	`assert`	`true`
	`principal`	none
`identity.otp`	`lifetime`	`300` s	Limits
	`attempts`	`5`
`identity.passkeys`	`algorithms`, `timeout`, `residence`, `verification`	`[-7, -257]`, `60000` ms, `required`, none	Settings
`identity.grants`	`lifetime`, `token`	`60` s, `2592000` s	Settings
`identity.clients`	`trust`, `lifetime`, `ttl`, `size`, `timeout`	`[]`, `3600` s, `2592000` s, `16384`, `3000` ms

§Secrets

Values that must not be written into the Context. Each is given as a $NAME reference and provided separately, as Configuration and Secrets describe.

Setting	What it is
`identity.tokens.keys[].key`	Token key, generated with `toa key`. At least one is required.
`identity.basic.pepper`	Password hashing pepper.
`identity.federation.trust[].secret`	A provider’s client secret.
`identity.federation.trust[].signature.key`	A provider’s private key for client assertions, PKCS8 PEM.

# context.toa.yaml
configuration:
  identity.tokens:
    keys:
      - id: 2026q4
        key: $IDENTITY_TOKENS_KEY
  identity.basic:
    pepper: $IDENTITY_BASIC_PEPPER
    principal:
      authority: local
      username: root
  identity.federation:
    trust:
      - iss: https://accounts.google.com
        aud: 1045282659797-example.apps.googleusercontent.com
        secret: $GOOGLE_CLIENT_SECRET

§Statuses

What a client of the application has to handle.

Status	Meaning	What to do
`401 Unauthorized`	The request has no identity and the route needs one: no credentials, or credentials that are wrong, expired, revoked, banned, from another authority, or of an unknown scheme. Also a token of another application used outside its resource.	Sign in again.
`403 Forbidden`	The identity is known and not admitted: no directive admits it, a custom token’s permissions exclude the request, the wrong scheme for an `auth:scheme` route, an unauthorized input property, credentials sent to an anonymous route, or a sign-up with credentials that already have an identity.	Do not retry as is.
`422 Unprocessable Entity`	Refused with a code: `INVALID_USERNAME`, `INVALID_PASSWORD`, `INVALID_CREDENTIALS`, `EXISTS`, `PRINCIPAL_LOCKED`, `INACCESSIBLE_SCOPE`, `UNKNOWN_CLIENT`, `FAILED`, `INVALID`, `MISS`, or a provider code.	Read `code`.
`409 Conflict`	The username is taken.	Choose another.
`429 Too Many Requests`	Too many failed sign-ins from this address, or a throttled endpoint.	Wait `retry-after` seconds.
`451 Unavailable For Legal Reasons`	The request matched `censor`.	Nothing.
`400 Bad Request`	A malformed `host`, a missing required header, a body that is not an object where `auth:delegate` applies, or an OAuth error with `error` and `error_description`.	Fix the request.

The body of a 401 or 403 does not say which reason applied, beyond the two texts quoted in Restrict Who Can Call a Route. The reason for rejected credentials is in the gateway’s log.

Alongside every successful status: a response may carry an authorization header, and the client must switch to the token in it.

The reasoning behind identities, tokens and access on routes is in the model.