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

# Authentication

> Use an API key to manage tiers, ads, fields, and more over the REST API.

Most of the Revinel API needs no credentials. The on-site surface (serving ads, tracking
impressions and clicks, listing tiers, and starting a checkout) runs in the browser and is scoped by
your public **workspace ID** in the path. See the [introduction](/docs/api/introduction#authentication)
for that surface.

The **management endpoints** are different. They let you run your workspace programmatically:
approve ads, edit tiers, manage custom fields, and more. Because they change your data, every request
must carry a secret **API key**. These endpoints are in beta; browse them under the **Beta** tags in
the API endpoints reference in the sidebar.

## Base URL

Every endpoint lives under one versioned base URL, over HTTPS:

```
https://api.revinel.com/v1
```

## Two ways to reach the API

|            | Public (no key)                                                   | Authenticated (API key)                                 |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Credential | Your **workspace ID** in the URL                                  | Secret **API key** in a header                          |
| Runs       | In the browser, on your own site                                  | Server-side only                                        |
| Can do     | Serve ads and tiers, track impressions and clicks, start checkout | Manage ads, tiers, prices, fields, advertisers, uploads |
| Endpoints  | `.../ads/serving`, `.../tiers/serving`, tracking, checkout        | Everything else under `/v1/workspaces/{id}/...`         |

<Warning>
  An API key is a secret. Treat it like a password: keep it server-side, never commit it to source
  control, and never ship it in client-side code. The browser surface uses your public workspace ID,
  not a key.
</Warning>

## Mint a key

Create keys in the dashboard under **Settings → General → API keys**.

<Steps>
  <Step title="Open the API keys card">
    Go to **Settings → General** and find the **API keys** card.
  </Step>

  <Step title="Create a key">
    Give the key a name you will recognize later (for example `Production server` or `Approval bot`)
    and select **Create key**.
  </Step>

  <Step title="Copy it now">
    The full key is shown **once**, right after you create it. It starts with `rvnl_`. Copy it and store
    it somewhere safe, like a secret manager. For your security, Revinel never shows it again. If you
    lose it, revoke the key and create a new one.
  </Step>
</Steps>

## Send the key

Pass the key in the HTTP `Authorization` header as a bearer token on every management request:

```bash theme={null}
Authorization: Bearer rvnl_...
```

For example, to list the ads in a workspace:

```bash cURL theme={null}
curl -H "Authorization: Bearer rvnl_..." \
  https://api.revinel.com/v1/workspaces/{workspaceId}/ads
```

A key is bound to a single workspace, so the `{workspaceId}` in the path must match the workspace the
key was created in. A key for one workspace cannot read or change another.

## Scope and least privilege

A key acts with the full permissions of the member who created it, within its one workspace. There
are no read-only or per-resource scopes yet, so lean on separate keys instead:

* **One key per integration.** Give each bot, CLI, or service its own named key. You can then revoke
  one without breaking the others, and an audit shows which integration did what.
* **Rotate by create-then-revoke.** Create the new key, deploy it, then revoke the old one on its row
  in the dashboard. A revoked key stops working immediately for anything still using it.
* **Keep it server-side.** See the warning above.

## What needs a key

<Note>
  Only the management endpoints require a key. The anonymous SDK surface (ad serving, tier serving,
  impression and click tracking, and checkout) works without one, because it is meant to run in the
  browser on your own site. Do not put an API key in that client-side code.
</Note>

## Rate limits

Each key gets a generous budget of 120 requests per minute. Over the limit, the API returns
`429 TOO_MANY_REQUESTS` with a `Retry-After` header (the number of seconds to wait). Back off and
retry once it passes. See [Rate limits](/docs/api/rate-limits) for every limit on the API.

## Errors

Every error is JSON with a machine-readable `code`, the HTTP `status`, and a human-readable `message`
(see the [error reference](/docs/api/introduction#error-handling)). The ones specific to authentication:

| Status | Code                | Meaning                                                      |
| ------ | ------------------- | ------------------------------------------------------------ |
| `401`  | `UNAUTHORIZED`      | The key is missing, malformed, or revoked.                   |
| `403`  | `FORBIDDEN`         | A valid key used against a workspace it is not scoped to.    |
| `429`  | `TOO_MANY_REQUESTS` | Over the per-key rate limit. Wait for `Retry-After` seconds. |