API overview

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.

Method	Path	Description
`POST`	`/v1/env/evaluate`	Evaluate a single variable
`POST`	`/v1/env/evaluate-batch`	Evaluate multiple variables in one request
`POST`	`/v1/env/pull`	Fetch 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.

Method	Path	Description
`POST`	`/v1/env/list`	List variable metadata for a stage (no plaintext values)
`POST`	`/v1/env/write`	Create or update variables; delete by name

CLI auth

Used by the CLI to establish and manage authenticated sessions via the device code flow.

Method	Path	Description
`POST`	`/v1/cli/device/start`	Start a new device authorization flow
`POST`	`/v1/cli/device/complete`	Approve a pending device code (called from the browser)
`POST`	`/v1/cli/device/poll`	Poll for authorization status (called by the CLI)
`POST`	`/v1/cli/token/refresh`	Rotate an expired access token using a refresh token
`POST`	`/v1/cli/logout`	Revoke a session
`GET`	`/v1/cli/session`	Inspect the current session associated with a token

Tooling

Method	Path	Description
`GET`	`/v1/typegen/manifest`	Fetch 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.

Overview

Environment API

CLI and tooling

Reference

Base URL

Endpoint groups

Variable evaluation

Variable management

CLI auth

Tooling

Request conventions

Headers

`x-request-id`

`x-barekey-request-key`

Response shape

​Base URL

​Endpoint groups

​Variable evaluation

​Variable management

​CLI auth

​Tooling

​Request conventions

​Headers

​x-request-id

​x-barekey-request-key

​Response shape

Base URL

Endpoint groups

Variable evaluation

Variable management

CLI auth

Tooling

Request conventions

Headers

`x-request-id`

`x-barekey-request-key`

Response shape