# Authentication

> API keys, the Authorization header, projects and spending limits.

Every API request is authenticated with a Clonvo API key sent as a bearer token.

```bash
curl https://api.clonvo.com/v1/key \
  -H "Authorization: Bearer $CLONVO_API_KEY"
```

The OpenAI SDKs send this header for you when you pass `api_key` (Python) or `apiKey` (Node.js). Clients that send the key in an `X-Api-Key` header instead also work.

## API keys

-   Keys start with `sk-cv-v1-` followed by 64 hexadecimal characters.
-   Clonvo stores only a keyed hash of each key, so the full key is shown once, when you create it. If you lose it, create a new key.
-   Each key belongs to a **project** in an **organization**. Requests made with the key are billed to that organization and reported under that project.
-   A key can be disabled, given an expiry date, or revoked. Revoked, disabled and expired keys, and keys in an archived project, are rejected with `401`. The error `code` says which: `api_key_revoked`, `api_key_disabled`, `api_key_expired` or `project_archived` (`missing_api_key` and `invalid_api_key` for a missing or unknown key).
-   Changes to a key take effect within about 15 seconds.

## Projects

Projects group API keys and usage, for example one project per app or environment. Every organization has a default project. How many active projects you can have depends on your [plan](https://clonvo.com/docs/plans.md): 5 on Free and 1,000 on Pay as you go. Archived projects don’t count, and creating or restoring one over the limit fails with `402` and the code `project_limit_reached`. In team organizations a project can be restricted to one team, so only that team’s members (plus owners and admins) can see it.

## Spending limits

From Pay as you go up, each key can have an optional spending limit in US dollars. Free only allows free models, so there’s nothing to limit.

| Reset | Behaviour |
| --- | --- |
| Daily, weekly or monthly | The key’s spend resets at the start of each period. |
| None | The limit applies to the key’s lifetime spend. |

Periods are in UTC: days start at 00:00, weeks on Monday, months on the 1st.

When a key has reached its limit, new requests with it fail with `402` and the code `key_limit_exceeded` until the period resets or you raise the limit. The message says when the limit resets. Use [`GET /v1/key`](https://clonvo.com/docs/other-endpoints.md#get-v1-key) to read a key’s limit and current usage.

The limit counts what Clonvo charges on the key: the cost of requests on credits, plus Clonvo’s fee on requests through [your own provider keys](https://clonvo.com/docs/byok.md) once you’re past the monthly allowance. Requests on your own keys within the allowance, and [free models](https://clonvo.com/docs/free-models.md), cost nothing and don’t count.

> **Note**
> 
> Spending limits are checked before each request starts. Requests that are already running when a limit is reached finish normally, so a key can go slightly over its limit.

## Organizations and roles

Credits, API keys, provider keys, projects and usage all belong to an organization. Everyone gets a personal organization at sign-up; you can also create team organizations and invite people as:

| Role | Can |
| --- | --- |
| Owner | Everything, including deleting the organization and making other people owners. |
| Admin | Manage projects, all API keys, provider keys, credit purchases, settings and members. |
| Member | See the projects open to everyone or to their teams; create API keys in those projects and manage the keys they created; view activity and usage for those projects, the credit balance and the playground. |

## Keeping keys safe

-   Call Clonvo from your server, not from browsers or mobile apps.
-   Use a separate key per app or environment so you can revoke one without affecting the others.
-   Set spending limits on keys used by scripts, CI or evaluation jobs.