# auth.md

> Machine-readable agent registration guide for the Xata API.
> Human-readable docs live at https://xata.io/docs.

This document describes how an AI agent can obtain credentials to call the Xata API at `https://api.xata.tech`.

Audience: autonomous agents. Human users should sign in at https://console.xata.io and create an API key from the dashboard.

## Discovery

- `https://xata.io/.well-known/api-catalog` — RFC 9727 API catalog with links to the OpenAPI spec, docs, and status page.
- `https://auth.xata.io/realms/xata/.well-known/openid-configuration` — OpenID Connect Discovery 1.0 metadata.
- `https://auth.xata.io/realms/xata/.well-known/oauth-authorization-server` — RFC 8414 OAuth 2.0 authorization server metadata.

The authoritative authorization server issuer is `https://auth.xata.io/realms/xata`. All endpoints below derive from its discovery document.

## Quick Start — Xata CLI

The fastest path for agents that can run a subprocess is the official Xata CLI, which performs an RFC 8628 device authorization grant against the issuer and exposes the resulting access token on stdout.

```bash
# macOS / Linux
curl -fsSL https://xata.io/install.sh | bash

# Windows
powershell -c "irm https://xata.io/install.ps1 | iex"

xata auth login                       # opens a browser for device-code flow
xata auth access-token                # prints a fresh access token to stdout
```

CLI docs: https://xata.io/docs/cli

Use the printed token as a bearer credential against `https://api.xata.tech`. The CLI refreshes the token automatically; calling `xata auth access-token` again returns a non-expired token.

## Manual Flows

### Option A — Device Authorization Grant (RFC 8628)

Agents without a browser of their own can drive the same device flow the CLI uses, against the endpoints advertised in the discovery document. The grant type is `urn:ietf:params:oauth:grant-type:device_code`.

### Option B — Dynamic Client Registration (RFC 7591)

Agents that can hold a long-lived secret can register an OAuth client against the issuer's dynamic client registration endpoint advertised in the discovery document.

```http
POST /realms/xata/clients-registrations/openid-connect HTTP/1.1
Host: auth.xata.io
Content-Type: application/json

{
  "client_name": "My Agent",
  "redirect_uris": ["https://my-agent.example.com/callback"],
  "grant_types": ["client_credentials", "authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_basic"
}
```

A successful response returns `client_id`, `client_secret`, and a `registration_access_token` that can be used to update or delete the registration later. Store these securely; the secret is shown only once.

If the realm has anonymous registration disabled (the default in production), this endpoint requires an `Authorization: Bearer <initial_access_token>` header. Initial access tokens are issued by a Xata administrator on request. Email security@xata.io with the agent name, intended scope, contact owner, and expected request volume to request one.

### Option C — API Keys

Long-lived API keys can be minted from `https://console.xata.io` or via the CLI:

```bash
xata keys user create          # personal key, scoped to the calling user
xata keys organization create  # organization-scoped key
```

Pass the key as a bearer token:

```http
GET /workspaces HTTP/1.1
Host: api.xata.tech
Authorization: Bearer <api_key>
```

User keys inherit the scope of the user that created them; organization keys are scoped to the organization.

### Option D — Standard OAuth 2.0 / OIDC Flows

Once registered, agents authenticate against `https://auth.xata.io/realms/xata/protocol/openid-connect/token` using any of the standard grant types advertised in the discovery document (`authorization_code` with PKCE, `refresh_token`, `client_credentials`, `urn:ietf:params:oauth:grant-type:device_code`, and others).

## Using the Credential

All authenticated requests use `Authorization: Bearer <access_token>` against `https://api.xata.tech`. Access tokens are JWTs signed by the issuer and can be introspected per RFC 7662 at `https://auth.xata.io/realms/xata/protocol/openid-connect/token/introspect`.

Supported scopes are advertised in `scopes_supported` of the discovery document. `openid`, `profile`, `email`, and `offline_access` are the common subset for agent flows.

## Revocation

Credentials may be revoked at `https://auth.xata.io/realms/xata/protocol/openid-connect/revoke` per RFC 7009, or by deleting the API key from `https://console.xata.io` or with `xata keys user delete` / `xata keys organization delete`.

## Error Handling

| Status | Meaning | Action |
|--------|---------|--------|
| 401 | Missing or invalid bearer token | Re-authenticate; refresh token if available |
| 403 | Token valid but lacks scope | Re-register with required scopes or contact the workspace owner |
| 404 | Resource does not exist or is not visible to the caller | Verify the workspace/branch identifier |
| 409 | State conflict (e.g. duplicate client registration) | Inspect the response body and reconcile |
| 429 | Rate limited | Back off exponentially; respect the `Retry-After` header |
| 5xx | Transient server error | Retry with exponential backoff and jitter |

## Contact

- General API docs: https://xata.io/docs
- CLI docs: https://xata.io/docs/cli
- Security and registration requests: security@xata.io
- Status: https://www.xatastatus.com