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

# Authentication

> Authenticate with the Carboncopy API using scoped API keys.

## Overview

All API endpoints are authenticated using **API keys**. Pass your key as a Bearer token in the `Authorization` header.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://carboncopy.inc/api/v1/portfolio \
  -H "Authorization: Bearer cc_your_key_here"
```

***

## API Keys

### Format

API keys follow the format `cc_` followed by 64 lowercase hexadecimal characters:

```
cc_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

### Creating a key

1. Log in to [Carboncopy](https://www.carboncopy.inc)
2. Navigate to [**Settings → API Keys**](https://www.carboncopy.inc/settings)
3. Click **Create Key**, choose a name and scopes
4. Copy the key — it's shown **exactly once** and cannot be retrieved later

### Scopes

Every key is issued with a set of scopes that control what it can access. Always issue keys with the minimum scopes your use-case requires.

| Scope       | Values                  | Controls                                                   |
| ----------- | ----------------------- | ---------------------------------------------------------- |
| `portfolio` | `none`, `read`          | View portfolio summary, history, and positions             |
| `traders`   | `none`, `read`, `write` | List/view traders (`read`); follow/edit/unfollow (`write`) |
| `orders`    | `none`, `read`, `write` | View orders (`read`); future order mutations (`write`)     |
| `markets`   | `none`, `read`          | Market data access (coming soon)                           |
| `account`   | `none`, `read`          | View account information                                   |

<Note>
  `write` scope implies `read` for the same resource. You don't need to grant both.
</Note>

### Key lifecycle

* Maximum **10 active keys** per account.
* Keys can have an optional expiry timestamp.
* Revoke a key anytime from [**Settings → API Keys**](https://www.carboncopy.inc/settings).

### Security best practices

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager.
</Warning>

* **Rotate regularly** — set an expiry and automate rotation in production.
* **Narrow scopes** — monitoring bots only need `portfolio:read`; they don't need `traders:write`.
* **One key per service** — easier to audit, easier to revoke if compromised.
* **Revoke immediately** if a key is exposed.

***

## Error responses

If authentication fails, the API returns a `401 Unauthorized`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}
```

If you authenticate successfully but your key lacks the required scope, you'll receive `403 Forbidden`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "forbidden",
    "message": "This key does not have the required scope."
  }
}
```

See [Errors](/errors) for the full error reference.