> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API authentication methods

## Local Mode

When Station runs in local mode (`local_mode: true`), no authentication is required:

```bash theme={null}
curl http://localhost:8585/api/v1/agents
```

## CloudShip Mode

When connected to CloudShip (`local_mode: false`), use one of these methods:

### Bearer Token

```bash theme={null}
curl -H "Authorization: Bearer your-token" \
  http://localhost:8585/api/v1/agents
```

### API Key

Generate an API key in Station settings:

```bash theme={null}
curl -H "X-API-Key: stn_xxx" \
  http://localhost:8585/api/v1/agents
```

## MCP Authentication

The MCP server (port 8586) uses OAuth when in CloudShip mode.

### OAuth Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Station
    participant CloudShip
    
    Client->>Station: MCP Request
    Station->>Client: 401 + OAuth Config
    Client->>CloudShip: Authorization Request
    CloudShip->>Client: Access Token
    Client->>Station: MCP Request + Token
    Station->>Client: MCP Response
```

### OAuth Configuration

Station advertises OAuth configuration:

```json theme={null}
{
  "oauth": {
    "authorization_url": "https://app.cloudshipai.com/oauth/authorize",
    "token_url": "https://app.cloudshipai.com/oauth/token",
    "client_id": "station-mcp",
    "scopes": ["mcp:read", "mcp:execute"]
  }
}
```

## Token Scopes

| Scope     | Permissions              |
| --------- | ------------------------ |
| `read`    | List agents, tools, runs |
| `write`   | Create/update agents     |
| `execute` | Run agents               |
| `admin`   | Full access              |

## Creating API Keys

### Via CLI

```bash theme={null}
stn auth create-key --name "CI Pipeline" --scopes "read,execute"
```

### Via API

```bash theme={null}
curl -X POST http://localhost:8585/api/v1/auth/keys \
  -H "Authorization: Bearer admin-token" \
  -d '{"name": "CI Pipeline", "scopes": ["read", "execute"]}'
```

## Revoking Keys

```bash theme={null}
stn auth revoke-key stn_xxx
```

Or via API:

```bash theme={null}
curl -X DELETE http://localhost:8585/api/v1/auth/keys/stn_xxx \
  -H "Authorization: Bearer admin-token"
```