# Authentication

> Authenticate Cevoid API requests with a scoped secret key sent as a bearer token, and verify the key with GET /v2/me.

Breadcrumb: API › Authentication · Updated: 2026-10-18
Docs index: https://docs.cevoid.com/developers/llms.txt

API v2 resource endpoints accept scoped secret keys as bearer tokens. Secret keys use the `cev_sk_` prefix and are shown only once, when you create them.

> [!WARNING]
> Legacy v1 keys do not work with API v2. See [API v1](https://docs.cevoid.com/developers/api/v1.md) if you still call `api.cevoid.com/v1`.

## Create a secret key

1. Go to [Settings → Integrations → Cevoid API](https://app.cevoid.com/settings/integrations/api)
2. Create a key for one integration and grant only the [scopes](https://docs.cevoid.com/developers/api/authentication#scopes) it needs
3. Copy the key and store it in your secret manager or an environment variable

## Send an API key

Pass your secret key in the `Authorization` header of every request:

```bash title="Authenticated request"
curl https://api.cevoid.com/v2/me \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

In TypeScript, read the key from the environment on the server:

```ts title="cevoid.ts"
const API_URL = "https://api.cevoid.com/v2"

export async function cevoid<T>(path: string, init: RequestInit = {}): Promise<T> {
  const headers = new Headers(init.headers)
  headers.set("Authorization", `Bearer ${process.env.CEVOID_API_KEY}`)
  headers.set("Content-Type", "application/json")

  const response = await fetch(`${API_URL}${path}`, { ...init, headers })
  if (!response.ok) {
    const error = await response.json()
    throw new Error(`${error.status} ${error.code}: ${error.message} (${error.request_id})`)
  }
  return response.json() as Promise<T>
}
```

> [!CAUTION]
> Never send a secret key from browser code. Anyone who opens your storefront can read it. For public storefront data, use the [Storefront API](https://docs.cevoid.com/developers/storefront-api.md) and its publishable key.

## Verify a key

Call [`GET /v2/me`](https://docs.cevoid.com/developers/api/authentication/get-authentication-details.md) to verify the key and inspect its workspace, scopes and configured [rate limits](https://docs.cevoid.com/developers/api/rate-limits.md):

```bash title="Verify a key"
curl https://api.cevoid.com/v2/me \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

```json title="200 OK"
{
  "data": {
    "id": "6f3ab66f14ebd9b9c67d1a31",
    "name": "Production integration",
    "type": "secret",
    "scopes": ["profiles:read", "orders:read"],
    "workspace": {
      "id": "6648c0f7bb9fd2d956fb0a42",
      "name": "Cevoid Demo"
    },
    "rate_limits": {
      "reads": 25,
      "writes": 10
    }
  }
}
```

> [!TIP]
> If `/v2/me` succeeds, the key is valid and ready to use.

If the request fails, the status tells you what to fix:

| Status | Meaning | Action |
| --- | --- | --- |
| `401` | Invalid or missing key | Check the `Authorization` header and that the key is a v2 secret key. |
| `403` | Missing permission | Create a key with the required scope. |

## Secret key scopes

Create a separate key for each integration and grant only the scopes it needs.

Two presets cover every resource, including resources added later:

| Preset | Access |
| --- | --- |
| `*` | Full access: read and write every resource |
| `*:read` | Read only: read every resource |

Grant individual scopes instead when an integration only needs part of the API:

| Scope | Access |
| --- | --- |
| `profiles:read` | Profiles, including profiles that have not joined the loyalty program |
| `members:read` | Loyalty membership details |
| `points:read` | Member point balances and transactions |
| `rewards:read` | Member rewards and redemption history |
| `tiers:read` | Tiers and member tier progress |
| `labels:read` | Labels for posts, profiles and reviews |
| `labels:write` | Create, update and delete labels |
| `markets:read` | Markets and localization settings |
| `products:read` | Products and variants |
| `posts:read` | Posts |
| `reviews:read` | Product and company reviews, ratings and summaries |
| `reviews:write` | Import product and company reviews |
| `review-requests:read` | Review requests |
| `orders:read` | Orders |
| `orders:write` | Create, update and delete orders |

A request outside the key's scopes returns `403`.

## Protect your keys

- Store keys in environment variables or a secret manager.
- Use separate keys for development, staging and production.
- Rotate keys by deploying a replacement before revoking the old key.
- Log `Cevoid-Request-Id`, not raw keys, when debugging requests.
- Never expose secret keys in browser code, public repositories, screenshots or customer-visible logs.

---

Canonical: https://docs.cevoid.com/developers/api/authentication