Authentication

This page covers the REST API. Connecting an agent over MCP instead? Most MCP clients skip keys entirely and use a browser login. See MCP.

API keys

Create and manage API keys from your API Keys page in the dashboard. Keys are tied to your organization.

There are two kinds:

Build against a sandbox key, then swap it for a live one. Nothing else about the request changes. See Sandbox for what it covers.

Header format

Include your API key in every request using the Authorization header:

Authorization: Bearer sk_live_YOUR_API_KEY

An X-API-Key header is also accepted, if that fits your HTTP client better:

X-API-Key: sk_live_YOUR_API_KEY

Example request

The SDKs read REDPINE_API_KEY from the environment (falling back to CONNECT_API_KEY) and send the Bearer header for you. Pass the key explicitly only when the environment is not the right place for it, such as a request-scoped key in a multi-tenant service.

curl -X POST "https://api.redpine.ai/api/v1/search/query" \
  -H "Authorization: Bearer sk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"collection": "my-collection", "query": "search text"}'

Constructing a client with no key available fails immediately with AuthError (Go: an error from New) rather than on the first request.

Key scoping

API keys can be scoped to control access:

• Organization-wide: access all collections in your organization.
• Collection-specific: restrict access to one or more named collections. Requests to other collections return 403.

Authentication errors

If the API key is missing, the API returns 401 Unauthorized with code UNAUTHORIZED. If it's present but doesn't match a live key, the code is INVALID_API_KEY; if it's been revoked, API_KEY_REVOKED:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "requestId": "req_a1b2c3d4"
  }
}

If the key is valid but lacks access to the requested collection, the API returns 403 Forbidden with code NO_COLLECTION_ACCESS. See Errors for the full list of codes.

If a sandbox key reaches an endpoint that has no sandbox behaviour, the API returns 403 SANDBOX_UNSUPPORTED_ENDPOINT rather than serving real data.

Security best practices

• Never expose API keys in client-side code or public repositories.
• Use collection-scoped keys when possible to limit blast radius.
• Rotate keys periodically and revoke unused keys.
• Store keys in environment variables or a secrets manager.