Skip to Content
Podyard

API_KEYS

List, create, and revoke Podyard API keys.

API_KEYS

Manage the API keys for your account. Keys are the authentication credential for all Podyard API calls.

Base: https://api.podyard.dev/v1

Note: The GET /v1/keys and POST /v1/keys endpoints require a deployment key (pyd_live_deploy_... or pyd_test_deploy_...), not a regular platform key. This is to prevent a compromised regular key from creating new keys.


GET /v1/keys — List API keys

Headers: Authorization: Bearer <deployment_key>.

Query params:

ParamTypeDefaultMaxDescription
cursorstring——Pagination cursor
limitint50200Page size

Response 200:

{
  "items": [
    {
      "id": "key_01J...",
      "label": "ci-pipeline",
      "kind": "live",
      "createdAt": "2026-01-15T10:30:00Z",
      "lastUsedAt": "2026-01-15T12:00:00Z",
      "revoked": false
    }
  ],
  "nextCursor": null
}

Security: The key secret (the pyd_live_... string) is never returned by this endpoint. Only the hash is stored. The secret is shown once at creation.


POST /v1/keys — Create an API key

Headers: Authorization: Bearer <deployment_key>, Content-Type: application/json, optional Idempotency-Key.

Body:

{
  "label": "ci-pipeline",
  "kind": "live"
}
FieldTypeRequiredDescription
labelstringyesHuman-readable label (e.g., ci-pipeline)
kindlive | testnoDefaults to live. test keys are for the sandbox environment.

Response 201:

{
  "id": "key_01J...",
  "label": "ci-pipeline",
  "kind": "live",
  "secret": "pyd_live_abc123def456...",
  "createdAt": "2026-01-15T10:30:00Z",
  "revoked": false
}

⚠️ The secret field is returned ONLY in this response. It is never available again. Store it securely immediately. The platform stores only a BLAKE2b-512 hash.

Errors: 401 unauthorized (invalid deployment key), 422 invalid_request.


DELETE /v1/keys/{id} — Revoke an API key

Headers: Authorization: Bearer <deployment_key>.

Response 204: empty body.

Revoking a key immediately invalidates it. Any in-flight requests using that key will fail with 401 unauthorized on their next call.

Errors: 401 unauthorized, 404 not_found.


ROTATION_WORKFLOW

  1. POST /v1/keys — create the new key. Note the secret.
  2. Update your CI / local env with the new secret.
  3. DELETE /v1/keys/{old_id} — revoke the old key.

WHERE_TO_GO_NEXT

  • Errors — full error code reference.
  • Webhooks — event notifications.