API keys

Every request to XField carries an API key. Keys belong to your account, you can have as many as you like, and each one can be disabled or deleted on its own. This page covers how to get one, how to send it, and how to keep it safe.

Getting access

XField is invite-only. Request access with a short note on what you plan to do. Once you are invited, sign in. Before your first API call, confirm the content policy in your account. Until you do, requests return a 403.

Creating a key

Open Settings › API keys and create a key.

• Name it after where it will live, such as laptop, ci, or claude-code. The name is how you will find it again.
• Expiry is optional. Pick 30 days, 90 days, a year, or never. Short-lived keys are a good default for shared machines and CI.

The full key is shown once, right after you create it. It starts with sk-xf-v1- followed by 64 hex characters. After that, the list only shows a short label so you can tell keys apart.

Rotating, disabling, and deleting

Each key in the list has three actions:

• Disable stops the key immediately. Requests with it get a 401. You can enable it again later, which is handy when you are not sure whether something still uses it.
• Delete removes the key for good.
• Rename changes the label, nothing else.

To rotate a key, create a new one, roll it out to wherever the old one is used, then disable the old key. Watch for errors for a day, then delete it.

Sending the key

Use whichever header your client sends. Both work on every route.

With the SDKs you rarely set headers yourself. Pass the key as api_key and the SDK does the rest.

import os
from openai import OpenAI
 
client = OpenAI(base_url="https://xfield.cloud.brutal.ai/api/v1", api_key=os.environ["XFIELD_API_KEY"])

Checking a key

GET /api/v1/key describes the key you call it with: its label, when it was created and last used, when it expires, and how many requests it has made. It is a cheap way to check that a key works before you wire it into something bigger.

curl https://xfield.cloud.brutal.ai/api/v1/key \
  -H "Authorization: Bearer $XFIELD_API_KEY"

{
  "data": {
    "label": "sk-xf-v1-3f2a…",
    "name": "laptop",
    "usage": 1284,
    "expires_at": null,
    "created_at": "2026-11-01T09:12:44.000Z",
    "last_used_at": "2026-11-05T14:03:10.000Z"
  }
}

Keeping keys out of repos

A leaked key is a key someone else can spend. A few habits help:

• Read the key from XFIELD_API_KEY, never from a string in your code.
• Keep .env files in .gitignore, and commit a .env.example with an empty value instead.
• Use a separate key per machine and per service, so one leak means one key to disable.
• In CI, store the key in the platform's secret store, not in the workflow file.
• Call the API from your server, not from a browser or mobile app, where anyone can read the key.

If a key does leak, disable it first and ask questions later.

When authentication fails

The error message says which case you hit. On /messages the error uses the Anthropic shape, with type set to authentication_error or permission_error. See Limits and errors for every other status.