Session and 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.

curl https://api.getdialed.ai/flows/me \
  -H "X-API-Key: $GETDIALED_API_KEY"

{
  "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.

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.

API keys

An API key authenticates requests through the X-API-Key header (see 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.

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

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

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.

Listing keys

GET /api-keys returns the converged Page 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.

{
  "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.

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.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

Session context: `GET /me`

API keys

Creating a key

Listing keys

Revoking a key

Next steps

Authentication

Monitoring and usage

​Session context: GET /me

​API keys

​Creating a key

​Listing keys

​Revoking a key

​Next steps

Authentication

Monitoring and usage

Session context: `GET /me`

API keys

Creating a key

Listing keys

Revoking a key

Next steps