API ReferenceBlogSign inGet started
GuidesDetectEnforceGovern

Credentials

Where to find your Project ID and API key, and which env var each Vouched KYA plane reads

Every Vouched KYA integration needs a Project ID. Server-side integrations (Middleware, Gateway, .NET, Java, a Govern/KYA-OS server) also need an API key; the browser surfaces (Pixel and Beacon) do not take one at all, since nothing in a page can hold a secret. The exception is a CDN you run in front of them, which holds the key in its own configuration; see Forward edge evidence. This page is the single source for where to find both, what they look like, and which environment variable each runtime reads.

Prerequisites

  • A Vouched KYA account with at least one project created.

Where to find them

Open Installations in the project's left-rail navigation (/dashboard/{orgId}/{projectId}/installations). Your Project ID is at the top of the page, with a copy button. Starting the Detect setup flow there (Configure & install → pick a layer) shows install snippets with the same Project ID and, for the server/middleware layer, a live API key pre-filled into the code sample.

You can also ask the dashboard assistant for a project's credentials; it renders a card where you generate the API key and copy it.

The key from Installations and from the assistant's card is read-only. That's enough for the server SDKs, which only read, but not for a server that writes to Vouched KYA: @kya-os/bouncer-middleware submitting proofs, or a self-hosted KYA-OS MCP server registering itself with POST /api/v1/kya-os/servers. For those, create a key under All settings → API keys in the user menu (/dashboard/{orgId}/account/api-keys) and choose the project as its scope. It gets read and write permission. An organization-wide key can't register a server: registration needs a key scoped to the project the server reports into. kya-os mcp create mints its server's key with write permission already.

With the CLI, you don't copy the Project ID at all: kya-os setup signs you in and links the repository to the project in .kya-os/project.json. A server SDK still needs an API key. When you're signed in, kya-os detect install --surface sdk mints one for the app and writes it to a gitignored .env.local (Next.js) or .env (Express). To use a key from the dashboard instead, store it with kya-os checkpoint key set, which prompts with hidden input and writes CHECKPOINT_API_KEY to .env.local. See the Quickstart.

Installations ships the Detect capability card today. If your integration is Enforce or Govern only, the same Project ID and API key values still apply: they're per-project, not per-capability.

Project ID

  • A name-based slug (e.g. acme-corp), or a UUID for older projects that have no slug: the value at the top of Installations, and the one the install snippets embed.
  • The same Project ID is used everywhere: the Pixel's data-project-id attribute, the Beacon's projectId config, the Next.js and Express projectId option, the .NET SDK's ProjectId option, and the Java SDK's projectId builder option.
  • Every integration also accepts the project's UUID. For now, one setup needs it: a server SDK with browser posture on refuses the slug. Find the UUID under All settings → Projects in the user menu (/dashboard/{orgId}/account/projects), listed as Project UUID with a copy button.

API key

  • Format: sk_ followed by a random hex string, e.g. sk_a1b2c3d4…. The exact length depends on which surface minted the key (dashboard-created keys are 64 hex characters; keys minted by a managed deploy are 48), so match on the sk_ prefix rather than on a fixed length.
  • API keys can be project-scoped (tied to one project) or user-scoped (not tied to any project): the dashboard derives this from whether a project is attached.
  • Keys can be revoked at any time; revocation takes effect immediately on the instance that revoked the key, but the API-key validator caches valid keys for up to 5 minutes, so another running instance can keep accepting a revoked key until that cache entry expires. There is no separate "rotate" action: revoke the old key and create a new one.

as_live_… is not a real Vouched KYA API key format. If you see that shape in older docs or examples, treat it as an error. Note the narrower claim: sk_… is what every current minting path generates. A bare as_… prefix is a real legacy format that no current path generates, but a key minted under that old scheme still authenticates if it was stored and never revoked, so validate by looking the key up, never by asserting a prefix.

Which env var to use

Every plane reads the same name, CHECKPOINT_API_KEY. What differs is whether the runtime picks it up from the environment on its own or needs it passed as a config option.

PlaneEnv varNotes
SDKs: Next.js, Express, .NET (ApiKey option)CHECKPOINT_API_KEYPass via the apiKey/ApiKey config option; the in-process Next.js and Express middleware and the .NET SDK require it explicit, with no environment fallback. The Next.js API client (withCheckpointApi) is the exception: it also reads this from the environment when apiKey is omitted.
SDK: Java (apiKey builder option)CHECKPOINT_API_KEYSet it with .apiKey(...), or leave it off: build() then reads CHECKPOINT_API_KEY from the environment, and ignores a value without the sk_ prefix, with a warning.
Managed-deploy worker, self-hosted KYA-OS serverCHECKPOINT_API_KEYRead from the runtime environment. Managed deploys set it as a Cloudflare Worker secret; a self-hosted bundle reads it from the secrets you configure.

The Project ID has the same split: SDKs and dashboard config take a plain projectId/ProjectId option, while the generated worker/deploy runtime reads CHECKPOINT_PROJECT_ID from its environment, which deploys provision (they set it to the project's friendly ID, the same Project ID Installations shows). The docs' own examples pass the Project ID from CHECKPOINT_PROJECT_ID (or NEXT_PUBLIC_CHECKPOINT_PROJECT_ID for browser surfaces): that's what the worker plane reads directly, but the in-process Next.js, Express, and .NET SDKs still need it passed as an explicit projectId/ProjectId option, not read from that env var. The Java SDK is the exception: with projectId left off the builder, it reads CHECKPOINT_PROJECT_ID.

Other environment variables the SDKs read

Beyond the API key, the @kya-os/checkpoint-nextjs API client (withCheckpointApi) reads these directly when the corresponding config field is omitted. CHECKPOINT_DEBUG is the exception: the API client combines it with the debug option by OR, so its logging turns on if either one is true and debug: false alone will not silence a CHECKPOINT_DEBUG=true environment; clear both to turn it off. The withCheckpoint middleware reads only its own debug option. All are optional.

Env varConfig equivalentEffect
CHECKPOINT_API_URLbaseUrlOverride the endpoint base. With edge mode on (the default) it replaces the detection gateway, https://detect.checkpoint-gateway.ai, and requests go to <base>/__detect/enforce; with CHECKPOINT_USE_EDGE=false it replaces the API origin (<base>/api/v1/enforce).
CHECKPOINT_USE_EDGEuseEdgeSet to false to call the Vercel-hosted API instead of the edge detection gateway. Any other value leaves it on.
CHECKPOINT_DEBUGdebugSet to true to log detection decisions and errors to the console. Enabled when either this or debug is true; see note above.
CHECKPOINT_SECRETencryptionKeyEncryption key for the session tracker. Set this in production: it otherwise falls back to a shared default.

The Beacon takes no API key. BeaconConfig accepts a projectId and nothing else credential-shaped: it runs in the browser, where an API key could not be kept secret anyway. If you are looking for where to put one, you do not need one.

Next Steps

Let your agent set it up

One command gives your coding agent the Vouched KYA skill. Ask it to add detection, block AI agents, or govern your coding agents, and it does the work, handing you only the steps that need your sign-in or approval.

Troubleshooting

Symptom-first index of common Vouched KYA issues: what you see, the likely cause, and the page that fixes it

On this page

PrerequisitesWhere to find themProject IDAPI keyWhich env var to useOther environment variables the SDKs readNext Steps