# auth.md

You are an agent. Spice Cloud supports machine authentication for API and MCP
access via **OAuth 2.0 client credentials**. Follow the steps in order.

Spice does **not** implement interactive agent registration (anonymous claim,
ID-JAG assertion exchange, or WorkOS-style agent_auth). Human users create
apps and credentials in the Spice Cloud portal; agents then use those
credentials.

## Step 1 — Discover

### 1a. Protected Resource Metadata (RFC 9728)

```http
GET https://spice.ai/.well-known/oauth-protected-resource
```

Example response shape:

```json
{
  "resource": "https://prod-api.spiceai.io",
  "authorization_servers": ["https://spice.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "apps:read",
    "apps:write",
    "apps:delete",
    "audit-log:read",
    "deployments:read",
    "deployments:write",
    "config:read",
    "config:write",
    "secrets:read",
    "secrets:write",
    "members:read",
    "members:write",
    "*"
  ],
  "resource_documentation": "https://docs.spice.ai/api/management-api/management"
}
```

- `resource` — canonical API resource identifier (use as token audience when applicable).
- `authorization_servers` — OAuth issuer base(s); fetch RFC 8414 metadata next.
- `scopes_supported` — scopes the resource server understands.
- `bearer_methods_supported` — how to send the access token (`"header"` = `Authorization: Bearer …`).

### 1b. Authorization Server Metadata (RFC 8414)

```http
GET https://spice.ai/.well-known/oauth-authorization-server
```

Example response shape:

```json
{
  "issuer": "https://spice.ai",
  "token_endpoint": "https://spice.ai/api/oauth/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "grant_types_supported": ["client_credentials"],
  "scopes_supported": [
    "apps:read",
    "apps:write",
    "apps:delete",
    "audit-log:read",
    "deployments:read",
    "deployments:write",
    "config:read",
    "config:write",
    "secrets:read",
    "secrets:write",
    "members:read",
    "members:write",
    "*"
  ],
  "service_documentation": "https://docs.spice.ai/api/management-api/management"
}
```

## Step 2 — Obtain credentials (human / out of band)

A human operator must create an application and OAuth client credentials in
Spice Cloud (portal at [https://spice.ai](https://spice.ai)). Agents receive:

- `client_id`
- `client_secret`

Do not invent credentials. If you do not have them, stop and ask the user to
provision an app and share client credentials (or a short-lived token).

## Step 3 — Exchange for an access token

```http
POST https://spice.ai/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=apps:read
```

Alternatively authenticate the client with HTTP Basic
(`token_endpoint_auth_methods_supported` includes `client_secret_basic`).

Request only the scopes you need. The wildcard scope `*` grants all scopes
listed in metadata when the client is allowed to use it.

Successful response is a standard OAuth token response with
`access_token`, `token_type` (Bearer), and optionally `expires_in` / `scope`.

## Step 4 — Call the Management API

```http
GET https://prod-api.spiceai.io/v1/...
Authorization: Bearer {access_token}
```

OpenAPI description:

```http
GET https://prod-api.spiceai.io/openapi.json
```

Human docs: [https://docs.spice.ai/api/management-api/management](https://docs.spice.ai/api/management-api/management)

## Step 5 — Call the Spice Cloud MCP server

MCP Server Card:

```http
GET https://spice.ai/.well-known/mcp/server-card.json
```

Streamable HTTP endpoint (from the card): `https://api.spice.ai/mcp`

Authenticate MCP requests with the same Bearer access token when the tool
requires Cloud API access.

## Public site content (no auth)

Marketing and docs content on spice.ai does **not** require OAuth:

- Site overview: [https://spice.ai/llms.txt](https://spice.ai/llms.txt)
- Full site markdown: [https://spice.ai/llms-full.txt](https://spice.ai/llms-full.txt)
- Agent skills index: [https://spice.ai/.well-known/agent-skills/index.json](https://spice.ai/.well-known/agent-skills/index.json)
- Per-page markdown: append `.md` to a page path, or send `Accept: text/markdown`

## Revocation and rotation

Rotate or delete client credentials in the Spice Cloud portal when access
should end. There is no public token-revocation endpoint separate from
credential rotation for the client_credentials grant.

## References

- Protected Resource Metadata: [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)
- Authorization Server Metadata: [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)
- Client Credentials: [RFC 6749 §4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
- MCP Server Card: [https://spice.ai/.well-known/mcp/server-card.json](https://spice.ai/.well-known/mcp/server-card.json)