# Authentication

How to create an API key, send it with each request, and what happens when it is missing, wrong or revoked.

Source: https://docs.itsconvo.com/authentication

API Base URL: https://www.itsconvo.com/api/v1

Every request needs an API key in the `Authorization` header. Keys work on the Starter, Professional and Enterprise plans.

```
Authorization: Bearer convo_...
```

<Tabs items={["curl", "JavaScript", "Python"]}>
<Tab value="curl">
```bash
curl https://www.itsconvo.com/api/v1/conversations \
  -H "Authorization: Bearer $CONVO_API_KEY"
```
</Tab>
<Tab value="JavaScript">
```javascript
const res = await fetch("https://www.itsconvo.com/api/v1/conversations", {
  headers: { Authorization: `Bearer ${process.env.CONVO_API_KEY}` },
});
const { data } = await res.json();
```
</Tab>
<Tab value="Python">
```python
import os
import requests

resp = requests.get(
    "https://www.itsconvo.com/api/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['CONVO_API_KEY']}"},
)
data = resp.json()["data"]
```
</Tab>
</Tabs>

## Create a key

1. Open the Convo desktop app and go to **Settings → Convo API**.
2. Click **Create key**, give the key a name and accept the API Terms of Use.
3. Copy the key. It is shown only once.

- A key is `convo_` followed by 32 hex characters. Convo stores only a SHA-256 hash of it, so a lost key can't be shown again. Create a new one.
- Starter allows 1 active key, Professional 3 and Enterprise 10. Each sign-in to the hosted [MCP server](/mcp) from Claude, ChatGPT or Cursor also takes a slot.
- All your keys share one [rate limit](/rate-limits) and one budget of [AI credits](/tiers).

## Revoke a key

In **Settings → Convo API**, click **Revoke** next to the key and confirm. The key stops working at once.

## Keep keys on your server

Send requests from your server, not from a browser. The API doesn't allow requests from other websites' pages (CORS), and a key in front-end code is visible to anyone. Read the key from an environment variable and keep it out of your repository.

## When authentication fails

Errors use the [error format](/errors).

| Status | Message | What to do |
|--------|---------|------------|
| `401 unauthorized` | `Missing or invalid Authorization header. Use: Bearer <api_key>` | Send the header, starting with `Bearer ` |
| `401 unauthorized` | `Invalid API key` | The key is wrong or revoked. Create a new one. |
| `403 forbidden` | `API access requires a Starter plan or above. …` | The account is on Free, or its subscription has ended. Upgrade at [itsconvo.com/pricing](https://www.itsconvo.com/pricing). |
| `403 forbidden` | `This credential only permits read-only MCP access. …` | The key came from an MCP sign-in and only works with the hosted MCP server. Create an API key in the app. |

Active and trialing subscriptions work. If a renewal is late, access continues for 48 hours after the billing period ends.