← Back to Docs

Authentication & API Keys

Developer

Authentication & API Keys

Programmatic access to Priiism — over both REST and MCP — is authenticated with a single kind of credential: a vk_ API key. This guide covers the full lifecycle of a key.

Key format

Every key is an opaque bearer secret of the form:

vk_{env}_{secret}

For example, vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. The vk_live_ marker plus the first few characters form a short, non-secret prefix that Priiism stores and displays so you can identify a key at a glance; the rest is the secret and is never stored.

Creating a key

  1. Open Account Settings → Developer.
  2. Choose a descriptive name (e.g. “CI deploy bot”).
  3. Decide whether the key is org-wide or project-scoped (see below).
  4. Pick its scopes — the capabilities it may use. See Scopes.
  5. Optionally set an expiry date.
  6. Create the key.

One-time reveal

The raw secret is shown exactly once, on the screen right after you create the key:

Copy this now — it will never be shown again.

Priiism stores only a one-way hash of the secret plus the short display prefix — the raw value is never persisted and cannot be recovered. If you lose a key before copying it:

A key’s secret can only be shown once, at creation time. If it was lost before copying, revoke it and create a new one.

Store the secret somewhere safe (a secrets manager or your CI provider’s encrypted variables). Treat it like a password: never commit it to source control or paste it into logs.

Using a key

Send the key as a Bearer token on the Authorization header. The same header works for both the REST surface and the MCP endpoint:

curl -H "Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://YOUR-APP-HOST/api/projects

A missing, malformed, unknown, revoked, or expired key is rejected before your request reaches any handler. See API Reference → Errors for the exact 401 / 422 / 403 response shapes.

Org-wide vs. project-scoped keys

Every key belongs to one organization. Beyond that, a key is either:

  • Org-wide — not tied to any single project. When using an org-wide key with a per-project operation (for example, over MCP), you name the target project explicitly in the request. The project must belong to the key’s organization.
  • Project-scoped — bound to one project at creation time. It can only act on that project; naming any other project is rejected. Prefer project-scoped keys for integrations that only ever touch a single project — it limits the blast radius if the key leaks.

Expiry

If you set an expiry date, the key stops working automatically once that time passes — no manual cleanup required. Expired keys are rejected exactly like revoked ones (a generic 401). Use expiry for short-lived automation and time-boxed access.

Revoking a key

Revoke a key any time from Account Settings → Developer. Revocation is immediate and permanent:

This key will stop working immediately. This cannot be undone.

Any request presenting a revoked key is rejected with the same generic 401 as an unknown key. Revoked keys remain listed (marked revoked) for audit purposes but can never be reactivated.

Rotation

There is no in-place rotation. To rotate, create a new key, update your integration to use it, verify it works, then revoke the old one. This guarantees a compromised secret can never be silently swapped back into service.

Renaming and re-scoping

You can rename a key or change its scopes at any time without affecting the secret — the token stays the same, only its label or permissions change. Narrow a key’s scopes as soon as an integration no longer needs a capability.

Next steps