Skip to content

Developers

Consent API documentation

Show your consent banner, record visitor choices, serve your policies and connect integrations with one HTTPS API. Built for custom sites, headless builds and server-side integrations.

  • Version 1.0
  • Updated 13 November 2026
  • HTTPS only, TLS 1.2 or higher

Base URL

https://consent.savira.com/api/v1
On this page

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.

  1. 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.

  2. 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>
  3. 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.

Script token compared with API key
DetailScript tokenAPI key
Looks like32 lowercase hexadecimal characters, for example 3f9a...0c1dsv_ followed by 32 lowercase hexadecimal characters
IdentifiesOne websiteOne Savira account (organisation)
Where it belongsThe URL pathOnly in the Authorization: Bearer sv_... header
Visible to the publicYes. It is part of the banner script's address on every pageNever. Keep it out of pages, URLs, logs and client-side code
ReachesThat website's banner script, published banner settings, consent recording and published policiesThe account's setup status, banner settings, publishable policies and Savira's tracker list
Stops workingWhen 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.

Consent API v1 endpoints
MethodPathCredentialReturnsCaching
GEThttps://consent.savira.com/{scriptToken}.jsScript token, in the pathThe hosted banner script (JavaScript)5 min, then up to 10 min stale
GET/banner/{scriptToken}Script token, in the pathThe published banner settings and cookie categories60 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 pathA published policy's HTML, date and version5 min, then up to 10 min stale
GET/plugin/validateAPI key, in the Authorization headerWhether the key works, and how far the account is set upNot cached
GET/plugin/configAPI keyThe published banner settings, categories and the website's script tokenNot cached
GET/plugin/documentsAPI keyThe account's published policies that can be shown on a pageNot cached
GET/plugin/patternsAPI keySavira's list of known tracking scripts and embeds, by category1 day, then up to 7 days stale
GEThttps://consent.savira.com/healthNone{ "status": "ok" } while the service is upNot cached

All endpoints answer any origin and are rate-limited per visitor address. See Errors and rate limits.

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.

Policy types
typePolicy
privacy_policyThe privacy policy
cookie_policyThe cookie policy
customAn account's custom policy, such as terms and conditions

Example 200 response

{
  "contentHtml": "<h2>Privacy policy</h2><p>...</p>",
  "publishedAt": "2026-10-30T05:02:11.000Z",
  "version": 4
}
  • contentHtml is 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.

Example request

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.

Example response

{ "valid": true, "scriptToken": "3f9a...0c1d", "hasWebsite": true, "hasBannerConfig": true }
What the setup flags mean
hasWebsitehasBannerConfigscriptTokenMeaning
falsefalsenullThe key works. The account's website is not registered yet
truefalseThe website's tokenThe website exists. No banner is published yet
truetrueThe website's tokenReady. 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}.

Example response

[
  { "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" }
]
Fields in each policy
FieldMeaning
typeprivacy_policy, cookie_policy or custom
shortcodeThe 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 _
nameA custom policy's own name; otherwise "Privacy Policy" or "Cookie Policy"
publishedAtWhen 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).

Example response

{
  "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 src that contains it. Use the first match: the most specific patterns come first.
  • Categories are analytics, marketing or functional. Match them to the website's categories by slug.

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.

Example responses

{ "statusCode": 404, "message": "Website not found", "error": "Not Found" }

{ "statusCode": 400, "message": ["consentToken must match /^[a-zA-Z0-9_-]+$/ regular expression"],
  "error": "Bad Request" }
Error responses and what to do
StatusMeaningAction
400The request breaks a rule. message is a string, or a list for field errorsFix the request. Do not retry it unchanged
401API key missing, unknown or revokedAsk the account owner for a working key
404Unknown or deleted website, or nothing published yetTreat as "nothing to show". Check again later, not on every page
429Rate limit exceededWait the number of seconds in Retry-After, then retry
5xxSavira could not answerRetry 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.

What is stored
Data storedHoldsChanged later?
A consent record, per choiceThe accepted category IDs, banner version, time, source, metadata, user agent and truncated IP addressNever. Records are only added
A visitor entry, per browser token and accountThe consentToken and the latest truncated IP addressIts address is refreshed with each choice
A log entry, per choiceThe website, banner version, categories, source, consentToken and truncated IP address, in the account's compliance logNever
An API key's last useThe time of the key's latest accepted callAt 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.

Need a hand?

Ask us about API keys, the banner script or a custom integration.

Contact us

Add consent to your site today

Sign up, register your website and add one script tag. Not sure where you stand first? Scan your website for free.

© Savira 2026. All rights reserved.Savira is operated under the registered business name savira.com, ABN 53 273 071 022.PO Box 2045, Hornsby Westfield NSW 1635

Savira provides consent management tools, templates and general information to help you manage privacy compliance. It is not legal advice and does not guarantee compliance. You remain responsible for your own compliance.