Provider credentials (BYOK)

Attach, list, rotate, and delete bring-your-own-key provider secrets. Secrets are sealed at rest and fingerprinted for display; the plaintext is never returned.

A BYOK provider credential lets Zumik call your provider account on your behalf. The raw secret is sealed at rest with AES-256-GCM and a one-way fingerprint is kept for display. The plaintext is never stored unencrypted, logged, or returned on any response. Credential ids are prefixed pcr_. See the BYOK setup guide.

All requests require a bearer API key. See authentication.

Attach a credential

POST /v2/provider-credentials

providerstringrequired

One of openai, anthropic, xai, google_gemini, fireworks_ai.

display_namestringrequired

A human label for the credential.

secretstringrequired

The raw provider secret. Must not be empty. Sealed at rest and fingerprinted; never returned.

metadataobject

Arbitrary JSON you attach for your own bookkeeping.

curl https://api.zumik.ai/v2/provider-credentials \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "Acme OpenAI prod",
    "secret": "sk-..."
  }'

{
  "id": "pcr_01jy7nmn67q9r0s1t2u3v4w5xy",
  "object": "provider_credential",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "provider": "openai",
  "status": "active",
  "display_name": "Acme OpenAI prod",
  "secret_fingerprint": "zfp_9a3c1e7b2d4f6a08",
  "created_at": "2026-06-15T16:30:41Z",
  "metadata": {}
}

idstring

Opaque credential id, prefixed pcr_.

objectstring

Always provider_credential.

project_idstring

The owning project.

providerstring

The provider, echoed back.

statusstring

active, disabled, or revoked.

display_namestring

The label you supplied.

secret_fingerprintstring

A short non-reversible fingerprint, prefixed zfp_, so you can recognize the key without it being reconstructable.

created_atstring

RFC 3339 creation timestamp.

metadataobject

The metadata you supplied.

List credentials

GET /v2/provider-credentials

curl https://api.zumik.ai/v2/provider-credentials \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "pcr_01jy7nmn67q9r0s1t2u3v4w5xy",
      "object": "provider_credential",
      "provider": "openai",
      "status": "active",
      "display_name": "Acme OpenAI prod",
      "secret_fingerprint": "zfp_9a3c1e7b2d4f6a08"
    }
  ]
}

Rotate a credential

POST /v2/provider-credentials/{credential_id}/rotate

Replaces the sealed secret in place. The id and any matching stay stable; only the sealed material and fingerprint change, and the status returns to active.

credential_idstringpathrequired

The pcr_... id to rotate.

secretstringrequired

The replacement secret. Must not be empty.

curl -X POST https://api.zumik.ai/v2/provider-credentials/pcr_01jy7nmn67q9r0s1t2u3v4w5xy/rotate \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secret": "sk-new..." }'

Returns the updated credential with a new secret_fingerprint.

Delete a credential

DELETE /v2/provider-credentials/{credential_id}

Drops the public credential and its sealed secret together, so nothing lingers at rest.

credential_idstringpathrequired

The pcr_... id to delete.

curl -X DELETE https://api.zumik.ai/v2/provider-credentials/pcr_01jy7nmn67q9r0s1t2u3v4w5xy \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

{
  "id": "pcr_01jy7nmn67q9r0s1t2u3v4w5xy",
  "object": "provider_credential.deleted",
  "deleted": true
}

Errors

Status	Code	When
400	`invalid_request_error`	`secret` is empty, or the secret could not be sealed.
401	`invalid_api_key`	Missing or invalid API key.
404	`invalid_request_error`	The credential does not exist in this project.

See the full table on errors.