Skip to main content
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 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:

​
Two ways to reach the API

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.

​
Mint a key

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

Open the API keys card

Go to Settings → General and find the API keys card.
2

Create a key

Give the key a name you will recognize later (for example Production server or Approval bot) and select Create key.
3

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.

​
Send the key

Pass the key in the HTTP Authorization header as a bearer token on every management request:
For example, to list the ads in a workspace:
cURL
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

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.

​
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 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). The ones specific to authentication: