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

# Authentication

> API keys, JWT tokens, and scopes for programmatic access.

# Authentication

The Miteos API supports two authentication methods:

## API Keys (Recommended for integrations)

Create API keys from your [API Keys page](https://platform.miteos.com/api-keys). Each key has specific scopes that control what it can access.

```bash theme={null}
curl -H "Authorization: Bearer mk_live_abc123..." https://api.miteos.com/tasks
```

API keys are prefixed with `mk_live_` (production) or `mk_test_` (sandbox).

### Available Scopes

| Scope                | Access                                 |
| -------------------- | -------------------------------------- |
| `tasks.read`         | List and view tasks                    |
| `tasks.write`        | Create, cancel, and manage tasks       |
| `agents.read`        | View agent status and history          |
| `agents.write`       | Pause, resume, guide, and kill agents  |
| `workspaces.read`    | List workspaces and files              |
| `workspaces.write`   | Create workspaces, upload/delete files |
| `billing.read`       | View plan, usage, and invoices         |
| `teams.read`         | View team members and roles            |
| `teams.write`        | Invite members, change roles           |
| `integrations.read`  | List connected integrations            |
| `integrations.write` | Connect/disconnect integrations        |
| `trading.read`       | View positions and strategies          |
| `trading.write`      | Execute trades, manage positions       |
| `social.read`        | View posts and accounts                |
| `social.write`       | Create posts, manage accounts          |
| `commerce.read`      | View wallet, cards, orders             |
| `commerce.write`     | Issue cards, create orders             |

### Creating an API Key

```bash theme={null}
POST /api-keys
{
  "name": "Production Backend",
  "scopes": ["tasks.read", "tasks.write", "agents.read"]
}
```

Response:

```json theme={null}
{
  "id": "key-abc123",
  "name": "Production Backend",
  "key": "mk_live_sk_abc123...",
  "scopes": ["tasks.read", "tasks.write", "agents.read"],
  "created_at": "2026-06-20T10:00:00Z"
}
```

<Warning>
  The full key is only shown once at creation. Store it securely — it cannot be retrieved later.
</Warning>

## JWT Tokens (For browser sessions)

Used by the web app and Desktop app. Obtained via login:

```bash theme={null}
POST /auth/login
{"email": "user@example.com", "password": "..."}
```

Returns:

```json theme={null}
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}
```

* Access tokens expire in 60 minutes
* Refresh tokens expire in 7 days
* Use `POST /auth/refresh` with the refresh token to get a new access token

## Using in the Playground

In the "Try It" panel on any API reference page:

1. Paste your API key in the Authorization field
2. The `Bearer ` prefix is added automatically
3. Click "Send" to make a live request to `api.miteos.com`

## Webhooks

Receive real-time events when tasks complete, agents need approval, etc.

Create webhooks from the [API Keys page](https://platform.miteos.com/api-keys) or via API:

```bash theme={null}
POST /api-keys/webhooks
{
  "url": "https://your-server.com/webhooks/miteos",
  "events": ["task.completed", "agent.approval_needed", "agent.error"]
}
```

Webhook payloads include an `X-Miteos-Signature` header for verification.