Authentication

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

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.

Legacy v1 keys do not work with API v2. See API v1 if you still call api.cevoid.com/v1.

Create a secret key

Go to Settings → Integrations → Cevoid API⁠
Create a key for one integration and grant only the scopes it needs
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:

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:

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>
}

Never send a secret key from browser code. Anyone who opens your storefront can read it. For public storefront data, use the Storefront API and its publishable key.

Verify a key

Call GET /v2/me to verify the key and inspect its workspace, scopes and configured rate limits:

Verify a key

curl https://api.cevoid.com/v2/me \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"

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
    }
  }
}

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.