API keys

Generated from DialerDigital/core commit 6e9f026f0a72 — spec openapi/dialer-v1.yaml v0.36.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Per-tenant API keys (sha256 at rest; plaintext shown once).

Endpoints

Method	Path	Summary
GET	/v1/api_keys	List API keys
POST	/v1/api_keys	Mint an API key
DELETE	/v1/api_keys/{id}	Revoke an API key

List API keys

GET /v1/api_keys

Ids, labels and revocation timestamps only — hashes are never exposed.

Responses

200

The tenant's keys.

Field	Type	Required	Description
api_keys	array of ApiKey	yes
api_keys[].id	string (uuid)	no
api_keys[].label	string	no
api_keys[].revoked_at	string (date-time) | null	no
api_keys[].last_used_at	string (date-time) | null	no	Rotation-hygiene clock: the last time this key authenticated SUCCESSFULLY. Written at most once a minute per key, so a fresh reading may lag by up to that much. null means it has not authenticated successfully since the column acquired a writer — not that the key was never presented.
api_keys[].created_at	string (date-time)	no

{
  "api_keys": [
    {
      "id": "7a3f0f7e-52a1-4f3d-9f9d-27e5a1b9c001",
      "label": "onboarding",
      "revoked_at": null,
      "created_at": "2026-06-01T12:00:00Z"
    }
  ]
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Mint an API key

POST /v1/api_keys

The plaintext token (dd_...) is returned ONCE and only its sha256 is stored. Rotate by minting a new key and revoking the old one.

Request body (JSON)

Field	Type	Required	Description
label	string	no	Free-form label (default "").

{
  "label": "postman-smoke-1751600000"
}

Responses

201

Key minted; token is the only time the plaintext is visible.

Field	Type	Required	Description
api_key	object (ApiKey)	yes	Key metadata — the token hash is never exposed.
api_key.id	string (uuid)	no
api_key.label	string	no
api_key.revoked_at	string (date-time) | null	no
api_key.last_used_at	string (date-time) | null	no	Rotation-hygiene clock: the last time this key authenticated SUCCESSFULLY. Written at most once a minute per key, so a fresh reading may lag by up to that much. null means it has not authenticated successfully since the column acquired a writer — not that the key was never presented.
api_key.created_at	string (date-time)	no
token	string	yes	Plaintext bearer token, shown exactly once.

{
  "api_key": {
    "id": "9a1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "label": "postman-smoke-1751600000",
    "revoked_at": null,
    "created_at": "2026-07-05T10:00:00Z"
  },
  "token": "dd_example_plaintext_shown_once"
}

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Revoke an API key

DELETE /v1/api_keys/{id}

Sets revoked_at; keys are never deleted. Idempotent revocation semantics.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

200

The revoked key.

Field	Type	Required	Description
api_key	object (ApiKey)	yes	Key metadata — the token hash is never exposed.
api_key.id	string (uuid)	no
api_key.label	string	no
api_key.revoked_at	string (date-time) | null	no
api_key.last_used_at	string (date-time) | null	no	Rotation-hygiene clock: the last time this key authenticated SUCCESSFULLY. Written at most once a minute per key, so a fresh reading may lag by up to that much. null means it has not authenticated successfully since the column acquired a writer — not that the key was never presented.
api_key.created_at	string (date-time)	no

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}