Skip to main content

​
Base URL

https://api.barekey.dev
All endpoints are versioned under /v1. Every request and response body is JSON. This is a hand-written API reference — there is no generated OpenAPI spec.

​
Endpoint groups

​
Variable evaluation

Used by applications and the SDK to read variable values at request time.
MethodPathDescription
POST/v1/env/evaluateEvaluate a single variable
POST/v1/env/evaluate-batchEvaluate multiple variables in one request
POST/v1/env/pullFetch all variables for a stage as a flat key→value map

​
Variable management

Used by the CLI and dashboard to create, update, list, and delete variables.
MethodPathDescription
POST/v1/env/listList variable metadata for a stage (no plaintext values)
POST/v1/env/writeCreate or update variables; delete by name

​
CLI auth

Used by the CLI to establish and manage authenticated sessions via the device code flow.
MethodPathDescription
POST/v1/cli/device/startStart a new device authorization flow
POST/v1/cli/device/completeApprove a pending device code (called from the browser)
POST/v1/cli/device/pollPoll for authorization status (called by the CLI)
POST/v1/cli/token/refreshRotate an expired access token using a refresh token
POST/v1/cli/logoutRevoke a session
GET/v1/cli/sessionInspect the current session associated with a token

​
Tooling

MethodPathDescription
GET/v1/typegen/manifestFetch variable metadata for type generation tools

​
Request conventions

Content-Type: All POST requests must include Content-Type: application/json. Authorization: All endpoints except /v1/cli/device/start require an Authorization: Bearer <token> header. See Authentication for the two token types. Request body: All POST endpoints accept a JSON body. Required fields are documented per endpoint. CORS: All endpoints respond to OPTIONS preflight requests with appropriate CORS headers.

​
Headers

​
x-request-id

An optional client-supplied request ID for tracing. If provided, it is echoed back in every response under the requestId field. If not provided, Barekey generates one. 
curl -H "x-request-id: my-trace-id-123" ...

​
x-barekey-request-key

An idempotency key for evaluation and pull requests. Barekey uses this to deduplicate billing events — if the same key is sent twice within a short window, the second request is not billed again. Use a stable, unique key per logical evaluation event (e.g. a request ID from your application): 
curl -H "x-barekey-request-key: req_abc123" \
     -H "Authorization: Bearer bk_at_..." ...
The request key must be unique per billing event. Reusing the same key for genuinely different requests will result in under-billing and may cause unexpected behavior.

​
Response shape

All successful responses return JSON with at minimum a requestId field. All error responses follow this shape: 
{
  "error": {
    "code": "VARIABLE_NOT_FOUND",
    "message": "No variable named 'DATABASE_URL' found in stage 'development'.",
    "requestId": "req_01hx..."
  }
}
See Error codes for the full list of codes and their HTTP statuses.