> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session and API keys

> Bootstrap the current session with GET /me and manage named API keys

Two endpoints back the account shell of an app built on GetDialed: `GET /me` tells the app who is calling and how, and the API-key endpoints let an admin mint, list, and revoke the keys that authenticate machine-to-machine callers.

## Session context: `GET /me`

`GET /me` returns everything an app needs to paint its shell in one call — no follow-up requests. It reflects the credentials on the request itself and reads nothing extra from the database.

```bash theme={null}
curl https://api.getdialed.ai/flows/me \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

```json theme={null}
{
  "account": {
    "id": "acct_a1b2c3d4",
    "name": "Acme Corp",
    "slug": "acme",
    "clerk_org_id": "org_a1b2c3d4",
    "status": "active"
  },
  "user": {
    "id": "user_a1b2c3d4",
    "role": "admin",
    "email": "ops@acme.example"
  },
  "auth_type": "clerk"
}
```

| Field       | Type           | Description                                                                                 |
| ----------- | -------------- | ------------------------------------------------------------------------------------------- |
| `account`   | object         | The caller's account: `id`, `name`, `slug`, `clerk_org_id`, `status`.                       |
| `user`      | object \| null | The signed-in user (`id`, `role`, `email`) — present only on the Clerk JWT path.            |
| `auth_type` | string         | `clerk` when a user is signed in, `api_key` when the request authenticated with an API key. |

<Note>
  On the API-key path there is no human identity, so `user` is `null` and `auth_type` is `api_key`. Key off `account.id` (or `clerk_org_id`) for tenant identity — never the mutable `slug`.
</Note>

## API keys

An API key authenticates requests through the `X-API-Key` header (see [authentication](/authentication)). Each account can hold multiple named keys, and all three management endpoints require an **admin** caller.

| Method   | Endpoint             | Purpose                                                             |
| -------- | -------------------- | ------------------------------------------------------------------- |
| `POST`   | `/api-keys`          | Mint a new named key. Returns `201`; the full secret is shown once. |
| `GET`    | `/api-keys`          | List every key for the account, active and revoked.                 |
| `DELETE` | `/api-keys/{key_id}` | Revoke a key. Returns `204`.                                        |

### Creating a key

Supply a human-readable `name`. The response is the **only** time the full secret is ever returned — copy it immediately.

```bash theme={null}
curl -X POST "$BASE_URL/api-keys" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline"}'
```

```json theme={null}
{
  "id": "ak_5f8d9c2b1a3e4f6079d8c1b2",
  "name": "CI pipeline",
  "key": "gdf_Xa9dLpQ2rT7vB0cE4hJ6kM8nP1sU3wZ5yA7bD9fG2iK",
  "display_prefix": "gdf_Xa9d",
  "status": "active",
  "created_at": "2026-07-19T18:00:00Z"
}
```

<Warning>
  The `key` field is returned **exactly once** at creation and is never retrievable again. Store it in your secret manager right away. If it is lost, revoke the key and mint a new one.
</Warning>

### Listing keys

`GET /api-keys` returns the converged [`Page`](/concepts/batches-and-executions) envelope with offset paging (`limit`, `skip`) and a real `total`. Only metadata and the short `display_prefix` are returned — the secret and its hash are never re-served.

```json theme={null}
{
  "items": [
    {
      "id": "ak_5f8d9c2b1a3e4f6079d8c1b2",
      "name": "CI pipeline",
      "display_prefix": "gdf_Xa9d",
      "status": "active",
      "created_at": "2026-07-19T18:00:00Z",
      "last_used_at": "2026-07-19T18:05:00Z"
    }
  ],
  "total": 1,
  "limit": 100,
  "skip": 0,
  "next_cursor": null
}
```

The `display_prefix` (first eight characters, e.g. `gdf_Xa9d`) lets you identify a key in a listing without exposing the secret. `last_used_at` reflects the most recent authenticated request, updated lazily.

### Revoking a key

`DELETE /api-keys/{key_id}` flips the key's `status` to `revoked`. The record survives for audit, but the key stops authenticating immediately — subsequent requests with it receive `401`. Revocation is permanent; there is no un-revoke.

<Note>
  Keys are account-scoped and admin-equivalent — there are no per-key scopes or expiry in this version. Rotate a key by minting a replacement and revoking the old one once callers have switched over.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    How the API key and Clerk JWT paths work on every request.
  </Card>

  <Card title="Monitoring and usage" icon="chart-line" href="/concepts/monitoring">
    Paint the dashboard and read usage analytics in one call each.
  </Card>
</CardGroup>