Apps

An app is the unit that app users belong to. It has a public app_key and a private app_secret.

App fields

field	type	notes
`id`	integer	numeric id used in management paths
`app_key`	string	public identifier, `app_...`
`owner_client_id`	integer	the owning client
`parent_app_id`	integer or null	set for a sub-app
`name`	string	up to 80 characters
`description`	string	up to 500 characters
`redirect_uris`	list of strings	allowed OAuth redirects
`allow_master_login`	boolean	per-app sign-in policy flag
`status`	`active` or `disabled`	disabled apps cannot issue tokens
`created_at`	unix seconds
`updated_at`	unix seconds

Create an app

curl -sS -X POST "$MANAGE/apps" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-app",
    "description": "The Acme dashboard",
    "redirect_uris": ["https://acme.example/cb"],
    "allow_master_login": false
  }'

Response:

{
  "id": 1,
  "app_key": "app_1a2b3c4d5e6f7a8b",
  "owner_client_id": 1,
  "parent_app_id": null,
  "name": "acme-app",
  "description": "The Acme dashboard",
  "redirect_uris": ["https://acme.example/cb"],
  "allow_master_login": false,
  "status": "active",
  "app_secret": "gsk_...",
  "warning": "Store app_secret now; it is not recoverable."
}

Store app_secret. It is shown once.

Create a sub-app

curl -sS -X POST "$MANAGE/apps" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme-app-mobile","parent_app_id":1}'

A sub-app shares its parent's user pool. Sub-apps cannot have sub-apps.

Update an app

curl -sS -X PATCH "$MANAGE/apps/1" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme-app","description":"Updated","status":"active"}'

redirect_uris may be a list or a newline-separated string.

Disable or enable

curl -sS -X PATCH "$MANAGE/apps/1" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"status":"disabled"}'

A disabled app cannot issue tokens and its app users cannot sign in.

Rotate the app secret

curl -sS -X POST "$MANAGE/apps/1/rotate-secret" -H "$AUTH"

This revokes every existing app secret and issues one new one. The response contains the new app_secret once.

Delete an app

curl -sS -X DELETE "$MANAGE/apps/1" -H "$AUTH"

Deleting an app deletes its app users and their keys.

Redirect URIs

A redirect URI must match exactly, including scheme, host, port and path. The authorization endpoint rejects anything that is not registered.

Listing

curl -sS "$MANAGE/apps" -H "$AUTH"
curl -sS "$MANAGE/apps?q=acme&page=1&per=50" -H "$AUTH"

The response includes total, page, per and an apps array. Each app carries users and subapps counts in the list view.

GAUTH