API keys

Descarga la proyección completa de la API pública: openapi.json.

Emitir y rotar tus API keys explica este recurso en prosa, con ejemplos ejecutables.

GET /api-keysCopiar el enlace a esta sección

List API keys

Every workspace credential minted through this family — an API key (workspace-wide) and a personal token (acts as one member) alike. The plaintext secret is never returned again after creation; every other field, including prefix (the first characters, for telling keys apart in a list), is safe to display. Also lists the test-mode (sk_test_) keys of this workspace's sandbox, marked livemode: false and carrying the sandbox's tenant_id.

curl https://api.vitrinadev.com/api/v1/api-keys \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": [
    {
      "id": "c1c1c1c1-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "name": "Website integration",
      "prefix": "sk_dCG1N",
      "scopes": [
        "contacts:read",
        "conversations:write"
      ],
      "created_at": "2026-09-15T20:11:31.575Z",
      "last_used_at": "2026-09-20T14:02:47.916Z",
      "expires_at": null,
      "revoked_at": null,
      "user_id": null,
      "rotated_at": null,
      "livemode": true
    }
  ]
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /api-keysCopiar el enlace a esta sección

Create API key (returns plaintext secret once)

scopes must come from this workspace’s permission catalogue (GET /me lists what the caller may grant) — an unknown or misspelled scope is refused with 400, never silently dropped. The response’s secret is the ONLY time the plaintext token is shown; store it now, the platform keeps only a hash from then on. livemode: false mints an sk_test_ key bound to this workspace's sandbox: it authenticates only there, so it can never read or write this workspace's real data (409 SANDBOX_NOT_PROVISIONED until a sandbox exists — POST /sandbox/automotive or POST /sandbox/clinic).

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/api-keys \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website integration",
    "scopes": [
      "contacts:read",
      "conversations:write"
    ]
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "id": "c1c1c1c1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Website integration",
    "prefix": "sk_dCG1N",
    "scopes": [
      "contacts:read",
      "conversations:write"
    ],
    "created_at": "2026-09-15T20:11:31.575Z",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null,
    "user_id": null,
    "rotated_at": null,
    "livemode": true,
    "secret": "sk_dCG1N…"
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /api-keys/{id}Copiar el enlace a esta sección

Revoke API key

Immediate and irreversible: every request bearing this key’s secret 401s from this point on. There is no un-revoke — mint a new key instead.

curl -X DELETE https://api.vitrinadev.com/api/v1/api-keys/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Responde: 204 · 400 · 401 · 403 · 404 · 409 · 429

POST /api-keys/{id}/rotateCopiar el enlace a esta sección

Rotate API key secret (returns new plaintext secret once)

A NEW secret for the SAME key — same id, name and scopes, so an integration keyed on this id keeps its identity. The OLD secret keeps authenticating for grace_period_hours (0-72, default 24) so a redeploy has time to pick up the new one; after that it 401s like any revoked credential. prefix changes — it is derived from the new secret. Refuses (404) a revoked or foreign key: rotating cannot bring one back to life. Audited (api_keys.rotate).

Cuerpo

curl -X POST https://api.vitrinadev.com/api/v1/api-keys/<id>/rotate \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_hours": 24
  }'

Ejemplo de respuesta (200)

{
  "data": {
    "id": "c1c1c1c1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "name": "Website integration",
    "prefix": "sk_9pQ2R",
    "scopes": [
      "contacts:read",
      "conversations:write"
    ],
    "created_at": "2026-09-15T20:11:31.575Z",
    "last_used_at": "2026-09-20T14:02:47.916Z",
    "expires_at": null,
    "revoked_at": null,
    "user_id": null,
    "rotated_at": "2026-09-22T20:11:31.575Z",
    "livemode": true,
    "secret": "sk_9pQ2R…",
    "grace_period_ends_at": "2026-09-23T20:11:31.575Z"
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429