Overview
Start in three steps
The Consent API shows the banners and policies you set up in your Savira account, and records what your visitors choose. Each call uses one of two credentials: a public script token or a secret API key.
Step 1: Register your website
Savira issues a script token when your website is registered. It identifies that one website and is safe to publish.
Step 2: Add the banner script
One tag, once on every page, before the closing
</body>tag.<script src="https://consent.savira.com/{scriptToken}.js" async></script>Step 3: Act on the choice
The script records choices. Holding back tracking scripts until they are allowed is your website's job. The WordPress plugin does it for WordPress sites.
Credentials
A script token identifies one website and is safe to publish. An API key identifies a whole Savira account and must stay on your server.
| Detail | Script token | API key |
|---|---|---|
| Looks like | 32 lowercase hexadecimal characters, for example 3f9a...0c1d | sv_ followed by 32 lowercase hexadecimal characters |
| Identifies | One website | One Savira account (organisation) |
| Where it belongs | The URL path | Only in the Authorization: Bearer sv_... header |
| Visible to the public | Yes. It is part of the banner script's address on every page | Never. Keep it out of pages, URLs, logs and client-side code |
| Reaches | That website's banner script, published banner settings, consent recording and published policies | The account's setup status, banner settings, publishable policies and Savira's tracker list |
| Stops working | When the website is deleted in Savira (every call then answers 404) | When it is revoked or rotated. Creating a new key revokes the current one (every later call answers 401) |
Neither credential reads consent records, contacts or anything else held in the Savira dashboard. One Savira account is associated with one domain, and most API key endpoints answer 404 until a website is registered.
Endpoints
Endpoints are served from https://consent.savira.com/api/v1, over HTTPS only (TLS 1.2 or higher). The banner script and the health check are served from https://consent.savira.com. Requests and responses are JSON (UTF-8) unless stated.
| Method | Path | Credential | Returns | Caching |
|---|---|---|---|---|
GET | https://consent.savira.com/{scriptToken}.js | Script token, in the path | The hosted banner script (JavaScript) | 5 min, then up to 10 min stale |
GET | /banner/{scriptToken} | Script token, in the path | The published banner settings and cookie categories | 60 s, then up to 5 min stale |
POST | /consent/{scriptToken} | Script token, in the path | { "consentToken": "..." } | Not cached |
GET | /policy/{scriptToken}/{type} | Script token, in the path | A published policy's HTML, date and version | 5 min, then up to 10 min stale |
GET | /plugin/validate | API key, in the Authorization header | Whether the key works, and how far the account is set up | Not cached |
GET | /plugin/config | API key | The published banner settings, categories and the website's script token | Not cached |
GET | /plugin/documents | API key | The account's published policies that can be shown on a page | Not cached |
GET | /plugin/patterns | API key | Savira's list of known tracking scripts and embeds, by category | 1 day, then up to 7 days stale |
GET | https://consent.savira.com/health | None | { "status": "ok" } while the service is up | Not cached |
All endpoints answer any origin and are rate-limited per visitor address. See Errors and rate limits.
Record consent
POST /consent/{scriptToken} records one visitor's choice: the categories they accepted. Each call adds a new record and changes none, so the account keeps a history of every choice a visitor made.
await fetch('https://consent.savira.com/api/v1/consent/3f9a...0c1d', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
consentToken: '2c6a1f0e-8d4b-4f7a-9e21-5b3c7d9a0f12', // random UUID, kept in the visitor's browser
acceptedCategoryIds: ['c1d2...8e90', 'd4e5...1a2b'], // from GET /banner/{scriptToken}
source: 'banner',
}),
});
// 201 Created: { "consentToken": "2c6a1f0e-8d4b-4f7a-9e21-5b3c7d9a0f12" }| Field | Required | Rules |
|---|---|---|
consentToken | Yes | Up to 64 characters: letters, digits, _ and -. Create it once per browser, at random, and keep it: the same token ties a visitor's choices together. Never use anything that identifies the person, such as an email address or customer ID. |
acceptedCategoryIds | Yes | The IDs of the categories accepted, each once. [] records that the visitor declined everything or withdrew. Include the required categories. Every ID must belong to this website's banner, in any of its published versions. |
source | No | "banner" (the default), "re_consent" or "api" |
metadata | No | A JSON object stored with the record. HTML is stripped from every string in it. Keep personal information out of it. |
Any other field is refused with status 400.
| Status | Meaning |
|---|---|
201 | Recorded. The body echoes consentToken |
400 | A field breaks the rules, or a category ID is not part of this website's banner. Nothing is recorded |
404 | Website not found, or no banner is published to record consent against |
429 | Too many requests from this address |
Category IDs from an older banner version are accepted, so a visitor whose page loaded just before a new version was published is not refused. The record still names the version published when it arrived.
Published policies
GET /policy/{scriptToken}/{type} returns the latest published version of one of the account's policies, as HTML to place in your own page.
| type | Policy |
|---|---|
privacy_policy | The privacy policy |
cookie_policy | The cookie policy |
custom | An account's custom policy, such as terms and conditions |
{
"contentHtml": "<h2>Privacy policy</h2><p>...</p>",
"publishedAt": "2026-10-30T05:02:11.000Z",
"version": 4
}contentHtmlis cleaned of scripts and unsafe markup by Savira and carries no styles of its own, so your page styles apply to it.- A newly published version shows within 5 minutes for most visitors, and within 15 minutes at most, because of caching.
- Draft versions are never served. Data subject request replies and breach notifications are emails, not policies, and are never served here.
- A 400 means an unsupported type. A 404 means the website was not found or no policy of that type is published.
Integration endpoints
Four read-only endpoints let a server-side integration, such as the WordPress plugin, connect a site to a Savira account. Call them from your server only, never from the client side, with the account's API key as a bearer token.
curl https://consent.savira.com/api/v1/plugin/validate \
-H "Authorization: Bearer $SAVIRA_API_KEY"A missing, unknown or revoked key gets 401 ({ "statusCode": 401, "message": "Unauthorized" }) from all four. Each accepted call updates the key's last-used time.
GET /plugin/validate
Checks a key and says how far the account is set up. It succeeds on a working key by itself, so check a key with this when it is entered, and again from time to time. The WordPress plugin checks hourly, subject to wp-cron.
{ "valid": true, "scriptToken": "3f9a...0c1d", "hasWebsite": true, "hasBannerConfig": true }| hasWebsite | hasBannerConfig | scriptToken | Meaning |
|---|---|---|---|
false | false | null | The key works. The account's website is not registered yet |
true | false | The website's token | The website exists. No banner is published yet |
true | true | The website's token | Ready. Embed the banner script with this token |
GET /plugin/config
The website's published banner, with its script token, so a server can build the banner script's address without exposing the key on the client side. It returns { "config": {...}, "categories": [...], "scriptToken": "..." }, shaped as in Banner settings, and answers 404 when no website is registered or no banner is published.
GET /plugin/documents
The account's published policies that are meant to be shown: the latest version of each. An empty array means none are published yet, and a custom policy written for email is left out. Fetch a policy's text with GET /policy/{scriptToken}/{type}.
[
{ "type": "cookie_policy", "shortcode": "savira_cookie_policy",
"name": "Cookie Policy", "publishedAt": "2026-10-12T00:41:09.000Z" },
{ "type": "custom", "shortcode": "savira_custom_terms_and_conditions",
"name": "Terms and Conditions", "publishedAt": "2026-10-20T07:15:44.000Z" },
{ "type": "privacy_policy", "shortcode": "savira_privacy_policy",
"name": "Privacy Policy", "publishedAt": "2026-10-30T05:02:11.000Z" }
]| Field | Meaning |
|---|---|
type | privacy_policy, cookie_policy or custom |
shortcode | The WordPress shortcode name: savira_ plus the type, or for a custom policy savira_custom_ plus its name in lowercase, with each run of other characters as _ |
name | A custom policy's own name; otherwise "Privacy Policy" or "Cookie Policy" |
publishedAt | When that version was published (UTC) |
GET /plugin/patterns
Savira's list of known tracking scripts and embeds, with the consent category each needs. It is the same for every account, so cache it for a day, as the response headers allow. It needs a key associated with an account and website (otherwise it answers 404).
{
"scripts": { "googletagmanager.com/gtm.js": "marketing", "googletagmanager.com": "analytics",
"connect.facebook.net": "marketing" },
"iframes": { "youtube.com/embed": "functional", "player.vimeo.com": "functional" }
}- A pattern matches a script's or an iframe's
srcthat contains it. Use the first match: the most specific patterns come first. - Categories are
analytics,marketingorfunctional. Match them to the website's categories byslug.
Errors and rate limits
Errors come back as JSON with the HTTP status in the body. Use the status, and only show message in logs.
{ "statusCode": 404, "message": "Website not found", "error": "Not Found" }
{ "statusCode": 400, "message": ["consentToken must match /^[a-zA-Z0-9_-]+$/ regular expression"],
"error": "Bad Request" }| Status | Meaning | Action |
|---|---|---|
400 | The request breaks a rule. message is a string, or a list for field errors | Fix the request. Do not retry it unchanged |
401 | API key missing, unknown or revoked | Ask the account owner for a working key |
404 | Unknown or deleted website, or nothing published yet | Treat as "nothing to show". Check again later, not on every page |
429 | Rate limit exceeded | Wait the number of seconds in Retry-After, then retry |
5xx | Savira could not answer | Retry later with a growing wait. Keep using what you last fetched. Check system status |
Rate limits
Each endpoint allows 60 requests a minute from one IP address, counted separately per endpoint. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the count restarts). A 429 also carries Retry-After. Visitors who share an address, such as an office network, share its limit, so cache what you can. Use of the API is also subject to the Fair Use Policy.
Cross-origin rules
Every endpoint sends Access-Control-Allow-Origin: *, so any website can call it from a browser. The API uses no cookies and expects none, so send no credentials from a browser. API key endpoints answer browsers too, but a key in a browser is a key exposed. Call them from the server side.
Health and system status
GET https://consent.savira.com/health answers { "status": "ok" } while the service is up. It performs no checks per request and is rate-limited like every other endpoint. For incidents, maintenance and uptime history, see status.savira.com.
Visitor data
The Consent API stores each choice with a random browser token, a truncated IP address and the browser's user agent. It never receives a visitor's name or email address, and it sets no cookies.
| Data stored | Holds | Changed later? |
|---|---|---|
| A consent record, per choice | The accepted category IDs, banner version, time, source, metadata, user agent and truncated IP address | Never. Records are only added |
| A visitor entry, per browser token and account | The consentToken and the latest truncated IP address | Its address is refreshed with each choice |
| A log entry, per choice | The website, banner version, categories, source, consentToken and truncated IP address, in the account's compliance log | Never |
| An API key's last use | The time of the key's latest accepted call | At each call |
Truncated addresses
An IPv4 address keeps its first three parts (203.0.113.57 is stored as 203.0.113.0). An IPv6 address keeps its first 48 bits (2001:db8:1:2::5 as 2001:0db8:0001::). Invalid addresses are not stored.
In the visitor's browser
The hosted script keeps __savira_t (the random token) and __savira_c (the latest choice) in localStorage, never in cookies.
The account holder sees these records in the Savira dashboard, where they also handle visitors' requests for access or erasure. Erasing a visitor there removes their personal details and keeps their consent records, as proof of what was agreed.