Swagger

API keys

4 endpoints.

4 endpoints

API keys

GET/api-key/list?projectId=List a project's API keys

A project's API keys. Requires membership on the project. Each key carries a value field with the raw key string (or null if it was issued before plaintext storage was added), but only for a project owner or admin; a viewer gets every other field with value omitted entirely.

Authentication: Bearer JWT (project member)

Input — query and path parameters

projectId string required
Project id (query parameter)

Output — example response (200)

{
  "apiKeys": [
    {
      "id": "ugtp_project_api_key_a1b2c3d4e5f6",
      "name": "Server key",
      "keyPrefix": "ugtp2_0123",
      "scopes": [
        "full_access"
      ],
      "isActive": true,
      "expiresAt": null,
      "lastUsedAt": "2026-06-18T12:00:00.000Z",
      "createdAt": "2026-06-18T12:00:00.000Z",
      "revokedAt": null,
      "value": "ugtp2_0123456789abcdef0123456789abcdef"
    }
  ]
}

Output — every status this endpoint answers with

StatusWhen
200API keys (value present, owner/admin only)
400Invalid request body or query parameters
401Missing or invalid credentials
403Authenticated but not permitted
Open in Swagger
POST/api-key/createCreate an API key

Mint a project API key. The raw key is returned here and also persisted alongside the hash used for authentication, so an owner or admin can retrieve it later from GET /api-key/list. Requires an owner/admin membership on the project named in the body. A project holds at most ONE active key: while an active key exists the request fails with 409, so revoke the current key first.

Authentication: Bearer JWT (project owner/admin)

Input — request body

projectId string required
Project the key belongs to
name string required
Key label
scopes string[] required
Key scopes; full_access is the only scope today

Input — example request

{
  "projectId": "ugtp_project_a1b2c3d4e5f6",
  "name": "Server key",
  "scopes": [
    "full_access"
  ]
}

Output — example response (201)

{
  "id": "ugtp_project_api_key_a1b2c3d4e5f6",
  "apiKey": "ugtp2_0123456789abcdef0123456789abcdef",
  "keyPrefix": "ugtp2_0123"
}

Output — every status this endpoint answers with

StatusWhen
201Created key
400Invalid request body or query parameters
401Missing or invalid credentials
403Authenticated but not permitted
404Resource not found
409Request conflicts with the current state of the resource
500Internal server error
Open in Swagger
GET/api-key/allList manageable API keys

API keys the caller can manage with their owning project, newest first, capped at 100: every key for platform staff (owner / system_admin), or just the caller's owner/admin projects' keys for a project admin. Backs the cross-project key console.

Authentication: Bearer JWT (platform staff or project owner/admin)

Output — example response (200)

{
  "apiKeys": [
    {
      "id": "ugtp_project_api_key_a1b2c3d4e5f6",
      "name": "Server key",
      "keyPrefix": "ugtp2_0123",
      "scopes": [
        "full_access"
      ],
      "isActive": true,
      "projectId": "ugtp_project_a1b2c3d4e5f6",
      "projectName": "Acme",
      "lastUsedAt": "2026-06-18T12:00:00.000Z",
      "createdAt": "2026-06-18T12:00:00.000Z",
      "revokedAt": null,
      "revokedBy": null
    },
    {
      "id": "ugtp_project_api_key_f6e5d4c3b2a1",
      "name": "Old key",
      "keyPrefix": "ugtp2_9876",
      "scopes": [
        "full_access"
      ],
      "isActive": false,
      "projectId": "ugtp_project_a1b2c3d4e5f6",
      "projectName": "Acme",
      "lastUsedAt": null,
      "createdAt": "2026-06-10T12:00:00.000Z",
      "revokedAt": "2026-06-17T09:30:00.000Z",
      "revokedBy": {
        "name": "Ada Admin",
        "email": "ada@acme.com"
      }
    }
  ]
}

Output — every status this endpoint answers with

StatusWhen
200API keys with owning project + revoker
401Missing or invalid credentials
500Internal server error
Open in Swagger
POST/api-key/:keyId/revokeRevoke an API key

Revoke an API key by id. Platform staff may revoke any key; a project owner/admin may revoke only keys in a project they manage. Backs the cross-project key console.

Authentication: Bearer JWT (platform staff or project owner/admin)

Input — query and path parameters

keyId string required
API key id

Output — every status this endpoint answers with

StatusWhen
204Revoked
401Missing or invalid credentials
403Authenticated but not permitted
404Resource not found
Open in Swagger