# Management API

The management API lets a client account manage its own apps, users, keys and
sessions.

Base: `https://auth.gumpworks.com/api/v1/manage`

Authenticate with a client management key.

```bash
export MANAGE="$GAUTH/api/v1/manage"
export AUTH="Authorization: Bearer gtk_..."
```

The management API also accepts `X-Api-Key: gtk_...`.

A client key can only see and change that client's own resources. Account-level
operations such as creating or deleting client accounts are reserved for the
service administrator.

## Meta

```bash
curl -sS "$MANAGE/health" -H "$AUTH"
curl -sS "$MANAGE/stats" -H "$AUTH"
curl -sS "$MANAGE/settings" -H "$AUTH"
```

`GET /settings` returns your app user sign-in policy and the allowed bounds.

## Account

```bash
curl -sS "$MANAGE/clients" -H "$AUTH"
curl -sS "$MANAGE/clients/1" -H "$AUTH"
```

A client key sees only its own account.

Self-service:

```bash
curl -sS -X POST "$MANAGE/clients/1/password" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"password":"a-long-password"}'

curl -sS -X POST "$MANAGE/clients/1/rotate-key" -H "$AUTH"
curl -sS -X POST "$MANAGE/clients/1/logout" -H "$AUTH"
```

## Account creation

`POST /accounts` and the URI-style `POST /tenants/{tenant}/accounts` create app
users. See [Account creation](accounts.md) for the full surface, including the
administrator paths.

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

See [Apps](apps.md) for create, update, rotate and delete.

## App users

```bash
curl -sS "$MANAGE/apps/1/users" -H "$AUTH"
curl -sS "$MANAGE/apps/1/users/a_9k2m4x" -H "$AUTH"
```

See [App users](app-users.md) for create, update, password, status and delete.

## Keys

See [Keys and rotation](keys.md).

## Sessions

```bash
curl -sS "$MANAGE/sessions" -H "$AUTH"
curl -sS -X DELETE "$MANAGE/sessions/42" -H "$AUTH"
```

A client key can revoke sessions that belong to it or to its apps.

## Audit

```bash
curl -sS "$MANAGE/audit?limit=100" -H "$AUTH"
```

A client key sees its own audit entries.

## Lockouts

```bash
curl -sS "$MANAGE/security/lockouts" -H "$AUTH"

curl -sS -X POST "$MANAGE/security/unblock" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"username":"alice"}'
```

You can unblock by `username`, `ip` or `key`. A client can clear its own app
user lockouts.

## Sign-in policy

```bash
curl -sS -X PATCH "$MANAGE/settings" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"app_user_policy":{"start_after":5,"cap":60,"burst_gap":300}}'
```

| field | bounds | meaning |
|---|---|---|
| `start_after` | 0-20 | free attempts before any cooldown |
| `cap` | 5-300 | maximum cooldown in seconds |
| `burst_gap` | 60-3600 | seconds of silence that ends a failure burst |

The server rejects values outside the bounds.

## Pagination

List endpoints accept `page` and `per`. `per` is clamped to 1-200 and defaults
to 50. Responses include `total`, `page` and `per`.

## Response shapes

Single objects are returned directly. Lists are wrapped in a named key such as
`apps`, `users`, `keys`, `sessions`, `requests` or `entries`.