Skip to main content
Every Barekey API request (except POST /v1/cli/device/start) requires an Authorization header with a Bearer token: 
Authorization: Bearer <token>
There are two valid token types.

​
CLI access token

CLI access tokens are issued by the device code flow when you run barekey auth login. They are the standard way to authenticate server-side integrations, CI/CD pipelines, and SDK usage. Format: bk_at_ prefix followed by a base64url-encoded random string. TTL: 1 hour. Refresh using POST /v1/cli/token/refresh with a refresh token (bk_rt_...). Example: 
curl -X POST https://api.barekey.dev/v1/env/evaluate \
  -H "Authorization: Bearer bk_at_8f3kLmNpQrSt..." \
  -H "Content-Type: application/json" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "production",
    "name": "DATABASE_URL"
  }'

​
Storing CLI tokens

In CI/CD environments, store the access token as a secret in your CI provider (GitHub Actions secrets, Vercel environment variables, etc.). Reference it as an environment variable in your application: 
# GitHub Actions
- name: Evaluate secrets
  env:
    BAREKEY_TOKEN: ${{ secrets.BAREKEY_ACCESS_TOKEN }}
  run: |
    curl -H "Authorization: Bearer $BAREKEY_TOKEN" ...

​
Token refresh

When the 1-hour access token expires, use the refresh token to get a new pair: 
curl -X POST https://api.barekey.dev/v1/cli/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "bk_rt_..."}'
The refresh token is valid for 30 days. Each refresh issues a new access token and a new refresh token — the old refresh token is immediately invalidated (rotation pattern).

​
Clerk JWT

Clerk JWTs are used by the web dashboard and by server-side applications that already have Clerk sessions. The JWT must carry an active org claim — a Clerk session without an active org cannot access the API. Example: 
curl -X POST https://api.barekey.dev/v1/env/evaluate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "production",
    "name": "DATABASE_URL"
  }'
Clerk JWTs are short-lived (typically 60 seconds) and are intended for use in browser-based or server-rendered contexts where Clerk manages the session. For long-running server processes, use CLI access tokens instead.

​
Org scoping

The org scope is determined by the token, not by request body parameters.
  • For CLI tokens: the org is fixed at session creation time (when you ran barekey auth login --org <slug>).
  • For Clerk JWTs: the org is the active org in the Clerk session.
The orgSlug in the request body must match the org from the token. If it doesn’t, the request returns 403 ORG_SCOPE_INVALID. You cannot use a token issued for org A to access org B’s variables by changing orgSlug in the request body.

​
Token priority

If a request provides both a Clerk JWT and a CLI access token (e.g. in a misconfigured client), Barekey processes the Clerk JWT first. The CLI access token is only evaluated if no valid Clerk identity is found.

​
Errors

ScenarioCodeHTTP
Missing or malformed Authorization headerUNAUTHORIZED401
Token not found or expiredUNAUTHORIZED401
Session revokedUNAUTHORIZED401
Token org doesn’t match request orgSlugINVALID_ORG_SCOPE403
User removed from org since token was issuedORG_SCOPE_INVALID403