Account creation

A tenant key creates app users under its own apps. The same operation is available as a pure API call and as a URI-style call.

style	path
pure API	`POST /api/v1/accounts`
URI style	`POST /api/v1/tenants/{tenant}/accounts`
URI style	`POST /api/v1/tenants/{tenant}/apps/{app}/accounts`

Authenticate with Authorization: Bearer gtk_....

Pure API

curl -sS -X POST "$API/accounts" \
  -H "Authorization: Bearer gtk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "app": "app_1a2b3c4d5e6f7a8b",
    "username": "alice",
    "password": "a-long-password",
    "email": "alice@example.com",
    "display_name": "Alice"
  }'

app accepts an app_key, a numeric app id or an app name. Omit it when the tenant owns exactly one app.

URI style

curl -sS -X POST "$API/tenants/c_4m2x9p/accounts" \
  -H "Authorization: Bearer gtk_..." \
  -H "Content-Type: application/json" \
  -d '{"app":"app_1a2b3c4d5e6f7a8b","username":"alice","password":"a-long-password"}'

curl -sS -X POST "$API/tenants/c_4m2x9p/apps/app_1a2b3c4d5e6f7a8b/accounts" \
  -H "Authorization: Bearer gtk_..." \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"a-long-password"}'

{tenant} accepts a cid or a username. A tenant key can only name itself; any other tenant returns 404.

Response

{
  "id": 1,
  "uid": "a_9k2m4x",
  "app_id": 1,
  "app_username": "alice",
  "email": "alice@example.com",
  "display_name": "Alice",
  "status": "active",
  "api_key_hint": "gak_abc12345",
  "created_at": 1761200000,
  "updated_at": 1761200000,
  "tenant": "c_4m2x9p",
  "app_key": "app_1a2b3c4d5e6f7a8b",
  "api_key": "gak_...",
  "warning": "Store api_key now; it is not recoverable."
}

Fields

field	required	notes
`app`	when the tenant has more than one app	`app_key`, numeric id or name
`username`	yes	3-32 characters: letters, digits, dot, underscore or hyphen
`app_username`	no	alias for `username`
`password`	yes	at least the server minimum, 10 characters by default
`email`	no
`display_name`	no

Behaviour

A duplicate app_username on the same app returns 409.
A tenant key naming another tenant returns 404, never 403, so tenants cannot probe for each other.
A tenant key cannot create a tenant account; that returns 403.
Accounts are created on the root app of a family. A user created through a sub-app is found by the root app at sign-in time.
The raw api_key is returned once. Only its hash is stored.

Errors

status	error	meaning
400	`invalid_request`	a field is missing or malformed
401	`unauthorized`	missing or invalid credential
403	`forbidden`	the credential cannot create that kind of account
404	`not_found`	the tenant or app is not in your scope
409	`conflict`	the username is already taken

Administrator

The service administrator can create tenant accounts and app users through the same two styles on the internal mount. Those paths are documented in the operator docs.

GAUTH