# API Keys & Authentication

Manage authentication for TeamDay — Personal Access Tokens for API/CLI, OAuth for web, and Claude API credentials for agent execution.

# API Keys & Authentication

TeamDay uses three types of credentials:

1. **Personal Access Tokens (PATs)** — for API calls and CLI automation
2. **OAuth tokens** — for web app and CLI interactive login
3. **Claude API credentials** — for powering agent execution

---

## Personal Access Tokens (PATs)

PATs authenticate API requests and CLI commands. They're tied to your user account and organization.

### Create a PAT

1. Go to **Settings** in the TeamDay web app
2. Navigate to **API Keys** or **Integrations**
3. Click **Create Personal Access Token**
4. Copy the token immediately — it's shown only once

Tokens start with `td_` prefix.

### Use with the API

```bash
curl -X GET "https://cc.teamday.ai/api/v1/agents" \
  -H "Authorization: Bearer td_your_token_here" \
  -H "Content-Type: application/json"
```

### Use with the CLI

```bash
# Set directly
teamday auth set-key "td_your_token_here"

# Or via environment variable (for CI/CD)
export TEAMDAY_API_TOKEN="td_your_token_here"
```

### Token Security

- Store tokens in a password manager or environment variable
- Never commit tokens to Git
- Rotate tokens periodically
- Revoke tokens you no longer need

---

## OAuth Login

OAuth provides interactive browser-based authentication with automatic token management.

### CLI OAuth

```bash
teamday auth login
```

What happens:
1. CLI generates a secure authorization code
2. Opens your browser to the TeamDay login page
3. You click **Authorize CLI**
4. Tokens are saved automatically to `~/.teamday/`

### Check Status

```bash
teamday auth status
```

```
Authenticated

Method: oauth
User ID: abc123xyz
Organization: org_456def
Expires: in 12 minutes
```

### Refresh Tokens

OAuth tokens expire after 15 minutes. Refresh manually:

```bash
teamday auth refresh
```

Refresh tokens last 90 days. After that, run `teamday auth login` again.

### Logout

```bash
teamday auth logout
```

---

## Claude API Credentials

TeamDay agents are powered by Claude (and optionally Gemini/OpenAI). By default, TeamDay provides Claude API access through the platform.

You can bring your own credentials for direct billing or higher rate limits.

### 6-Tier Priority System

TeamDay selects credentials in priority order:

| Priority | Tier | Description |
|----------|------|-------------|
| 1 | **user-oauth** | Your personal Claude subscription OAuth token |
| 2 | **user-api** | Your personal Anthropic API key |
| 3 | **org-oauth** | Organization-shared OAuth token |
| 4 | **org-api** | Organization-shared API key |
| 5 | **server-oauth** | TeamDay platform token |
| 6 | **server-api** | TeamDay platform API key |

If a tier's token is suspended or has insufficient credits, TeamDay automatically falls through to the next available tier.

### Check Credential Status

```bash
teamday keys status
```

```
Claude Credential Status

User-level:
  OAuth Token:  configured
  API Key:      not set

Organization-level:
  Org: abc123
  OAuth Token:  not set
  API Key:      not set

Active Tier:
  user-oauth

Priority: user-oauth > user-api > org-oauth > org-api > server
```

### Set Credentials

```bash
# Your Claude subscription OAuth token (from claude.ai)
teamday keys set oauth sk-ant-oat01-your-token-here

# Your Anthropic API key
teamday keys set api-key sk-ant-api03-your-key-here

# Organization-level credentials
teamday keys set org-oauth sk-ant-oat01-org-token --org <orgId>
teamday keys set org-api-key sk-ant-api03-org-key --org <orgId>
```

### Remove Credentials

```bash
teamday keys remove oauth
teamday keys remove api-key
teamday keys remove org-oauth --org <orgId>
```

### Where to Get Claude Credentials

| Type | Source |
|------|--------|
| **OAuth token** | [claude.ai](https://claude.ai) subscription → Settings → API |
| **API key** | [console.anthropic.com](https://console.anthropic.com) → API Keys |

---

## API Endpoints

All API endpoints use the base URL `https://cc.teamday.ai/api/v1/`.

### Agents

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/agents` | List agents |
| `POST` | `/agents` | Create agent |
| `GET` | `/agents/:id` | Get agent details |
| `PATCH` | `/agents/:id` | Update agent |
| `DELETE` | `/agents/:id` | Delete (archive) agent |
| `POST` | `/agents/:id/execute` | Execute agent with a message |

### Spaces

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/spaces` | List spaces |
| `POST` | `/spaces` | Create space |
| `GET` | `/spaces/:id` | Get space details |
| `PATCH` | `/spaces/:id` | Update space (add/remove resources) |
| `POST` | `/spaces/:id/secrets` | Store secrets |
| `DELETE` | `/spaces/:id/secrets` | Remove secrets |

### Missions

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/missions` | Create mission |
| `PATCH` | `/missions/:id` | Update mission |

### MCPs

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/mcps` | List MCP instances |
| `POST` | `/mcps` | Create MCP instance |
| `GET` | `/mcps/:id` | Get MCP details |
| `PATCH` | `/mcps/:id` | Update MCP |

### Skills

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/skills` | Create skill |

### Profile

| Method | Endpoint | Description |
|--------|----------|-------------|
| `PUT` | `/profile/api-key` | Set Claude API key |
| `PUT` | `/profile/oauth-token` | Set Claude OAuth token |

---

## CI/CD Integration

### GitHub Actions

```yaml
jobs:
  run-agent:
    runs-on: ubuntu-latest
    env:
      TEAMDAY_API_TOKEN: ${{ secrets.TEAMDAY_TOKEN }}
      TEAMDAY_API_URL: https://cc.teamday.ai
    steps:
      - name: Install TeamDay CLI
        run: |
          git clone https://github.com/TeamDay-AI/teamday.git /tmp/teamday
          cd /tmp/teamday/packages/cli && bun install && bun link

      - name: Run agent
        run: |
          teamday agents exec ${{ vars.AGENT_ID }} \
            "Generate the daily report" --no-stream
```

### Direct API Call (No CLI)

```yaml
      - name: Run agent via API
        run: |
          curl -X POST "https://cc.teamday.ai/api/v1/agents/$AGENT_ID/execute" \
            -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"message": "Generate the daily report"}'
```

---

## Troubleshooting

### 401 Unauthorized

```bash
teamday auth status     # Check if authenticated
teamday auth refresh    # Refresh expired token
teamday auth login      # Re-authenticate
```

### 501 Agent Execution Error

Usually means no Claude API credential is configured:

```bash
teamday keys status                              # Check what's configured
teamday keys set oauth sk-ant-oat01-your-token   # Set your Claude token
```

### Rate Limiting

If you hit rate limits, you'll receive a `429` response. Wait and retry, or configure your own Claude API credentials for higher limits.

---

## Next Steps

- [CLI Tool](https://docs.teamday.ai/guides/cli-tool) — Full CLI command reference
- [Missions API Guide](https://docs.teamday.ai/guides/missions-api-guide) — Schedule automated tasks
- [API Reference](https://docs.teamday.ai/api) — Complete API documentation