Skip to content
engage-ai

API reference

API keys

Issue, list and revoke your organization's API keys

For concepts and a walkthrough, read API keys.

List API keys

GET/api-keys

Metadata only. Secrets are not stored in a recoverable form.

Auth
Session token or API key

Responses

  • 200Every key, including revoked ones.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl "https://api.getengageai.app/api-keys" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
[
  {
    "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
    "name": "CI pipeline",
    "prefix": "eng_live_312cf6e6",
    "scopes": [
      "string"
    ],
    "lastUsedAt": "2026-10-16T09:30:00.000Z",
    "expiresAt": "2026-10-16T09:30:00.000Z",
    "revokedAt": "2026-10-16T09:30:00.000Z",
    "createdAt": "2026-10-16T09:30:00.000Z"
  }
]

Issue an API key

POST/api-keys

Issue a replacement, migrate your callers to it, then revoke the old one — that is the rotation path, and it needs no downtime and no admin credential. The plaintext is shown once.

Auth
Session token or API key
Body
application/json

Request body

  • namestringrequired

    How you will recognise it later, e.g. "CI".

    Max 128 characters

  • scopesstring[]

    Defaults to ["*"].

  • expiresAtstring (date-time)

    Omit for a key that does not expire.

  • environmentenum

    One of live, test

Response fields 201
  • idstring (uuid)required
  • namestringrequired
  • prefixstringrequired
  • scopesstring[]required
  • lastUsedAtstring (date-time) | nullrequired
  • expiresAtstring (date-time) | nullrequired
  • revokedAtstring (date-time) | nullrequired
  • createdAtstring (date-time)required
  • plaintextstringrequired

    Shown exactly once.

Responses

  • 201Issued. Store the plaintext now.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X POST "https://api.getengageai.app/api-keys" \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline",
    "environment": "live"
  }'
Response · 201
{
  "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "name": "Trailhead Mid GTX Boot",
  "prefix": "eng_live_312cf6e6",
  "scopes": [
    "string"
  ],
  "lastUsedAt": "2026-10-16T09:30:00.000Z",
  "expiresAt": "2026-10-16T09:30:00.000Z",
  "revokedAt": "2026-10-16T09:30:00.000Z",
  "createdAt": "2026-10-16T09:30:00.000Z",
  "plaintext": "eng_live_312cf6e6.fPCz8Qk…"
}

Revoke an API key

DELETE/api-keys/{id}

Immediate and irreversible. The row is kept rather than deleted, so what a compromised key could reach stays auditable.

Auth
Session token or API key

Path parameters

  • idstring (uuid)required
Response fields 200
  • revokedtruerequired

Responses

  • 200Revoked.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X DELETE "https://api.getengageai.app/api-keys/$ID" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "revoked": true
}