# Account

Your partner account — branding, mode, and settlement currency — plus
self-serve **API key management**: list, mint, and revoke keys without leaving
the API.

## GET /v1/account

Retrieve the authenticated account. A quick way to confirm an API key is valid
and learn which mode (`live` or `test`) it operates in.

**Scope:** Authenticated (any valid key)

### Example request

```bash
curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "id": "ten_8f2a1c4d5e6f7a8b9c0d1e2f",
  "name": "Acme Live Events",
  "mode": "test",
  "status": "active",
  "branding": {
    "logoUrl": "https://acme.example/logo.png",
    "supportEmail": "support@acme.example",
    "primaryColor": "#e11d48"
  },
  "currency": "USD"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Your account id. |
| `name` | string | Account display name. |
| `mode` | string | `live` or `test` — which environment this key operates in. |
| `status` | string | Account status, e.g. `active`. |
| `branding` | object | Branding configuration for hosted pages — `logoUrl`, `supportEmail`, `primaryColor`, `emailDomain`. |
| `currency` | string | Your settlement currency (defaults to `USD`). |

---

## GET /v1/account/keys

List your API keys, newest first. Revoked keys stay in the list (with
`revoked_at` set) as an audit trail. The secret itself is **never** returned —
only its prefix.

**Scope:** `keys:manage`

### Example request

```bash
curl https://api.ticketconnect.example/v1/account/keys \
  -H "Authorization: Bearer sk_test_your_key_here"
```

### Example response

```json
{
  "data": [
    {
      "prefix": "sk_test_9f8e7d",
      "label": "Backend (staging)",
      "mode": "test",
      "kind": "secret",
      "scopes": ["events:read", "tickets:issue"],
      "created_at": "2026-07-01T10:00:00.000Z",
      "last_used_at": "2026-07-11T08:59:00.000Z",
      "revoked_at": null
    }
  ]
}
```

---

## POST /v1/account/keys

Mint a new API key. The plaintext `secret` is returned **exactly once**, in
this response — copy it straight into your secrets manager.

No privilege escalation is possible: the minted key's `scopes` must be a
subset of the calling key's scopes (a `*` wildcard key can mint anything,
including another `*` key), and a test-mode key can never mint a live-mode
key. Active keys are capped at **25 per account** (shared with keys created in
the dashboard).

**Scope:** `keys:manage`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | No | A display label, up to 80 characters. |
| `mode` | string | No | `live` or `test`. Defaults to the calling key's mode. A test key cannot mint a live key. |
| `scopes` | string[] | No | Scopes for the new key — must be a subset of the calling key's. Defaults to the caller's scopes. |
| `kind` | string | No | `secret` (default) or `publishable`. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/account/keys \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Door scanner",
    "scopes": ["scanning:write"]
  }'
```

### Example response

```json
{
  "prefix": "sk_test_2b4c6d",
  "label": "Door scanner",
  "mode": "test",
  "kind": "secret",
  "scopes": ["scanning:write"],
  "created_at": "2026-07-11T09:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "secret": "sk_test_2b4c6d...shown_only_once"
}
```

> Errors: `400 parameter_invalid` (bad label/scopes/mode/kind),
> `403 scope_escalation` (requested scopes exceed the caller's),
> `403 mode_escalation` (test key minting live), `409 key_limit_reached`
> (25 active keys — revoke unused keys first).

---

## DELETE /v1/account/keys/{prefix}

Revoke a key by its prefix. Revocation is **immediate** — the next request
with the revoked key gets a `401` — and **idempotent**. The calling key can
never revoke itself, so a rotation always overlaps: mint the new key, deploy
it, then revoke the old one with the new key (or any other key holding
`keys:manage`).

**Scope:** `keys:manage`

### Path params

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `prefix` | string | Yes | The key prefix, as shown in `GET /v1/account/keys`. |

### Example request

```bash
curl https://api.ticketconnect.example/v1/account/keys/sk_test_9f8e7d \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -X DELETE
```

### Example response

```json
{ "prefix": "sk_test_9f8e7d", "revoked": true, "revoked_at": "2026-07-11T09:05:00.000Z" }
```

> Errors: `400 cannot_revoke_self` (a key cannot revoke itself),
> `404 resource_missing` (no key with that prefix on your account).