Authentication

truConsent uses two authentication methods depending on the type of endpoint you are calling. Most endpoints use an API key passed in a request header. Endpoints that manage consent links on behalf of a logged-in user require a Bearer token instead.

API key authentication

An API key identifies your organization and authorizes server-to-server requests. Include it in the X-API-Key header on every request to protected endpoints.

Where to get your API key: Log in to your truConsent dashboard and go to Settings → API Keys. Generate a new key and copy it immediately — the dashboard will not show the plaintext value again.

Which endpoints require it: All consent, banner, and user rights endpoints use API key authentication.

curl -X POST https://api.truConsent.io/consent/your-collection-point-id/consent \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Caution

Keep your API key secret. Do not embed it in client-side JavaScript, mobile app binaries, or any code that runs in an untrusted environment. Treat it like a password — if it is compromised, revoke it from the dashboard immediately and generate a new one.

Bearer token authentication

Consent link management endpoints require a Bearer token tied to an authenticated user in your organization. Pass the token in the Authorization header.

Affected endpoints:

• POST /api/outside-app/consent-link/create
• POST /api/outside-app/consent-link/regenerate/{request_id}
• GET /api/outside-app/consent-link/history

curl -X POST https://api.truConsent.io/api/outside-app/consent-link/create \
  -H "Authorization: Bearer your-bearer-token" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Note

Bearer token authentication verifies that the caller is an active member of your organization’s truConsent account. You obtain this token through your authentication provider session — it is not generated from the truConsent dashboard.

Tenant routing

Every truConsent organization has its own subdomain (for example, acme.api.truConsent.io). All requests must be sent to your organization’s subdomain so the API can route them to the correct data store. Sending a valid API key to the wrong subdomain will result in an authentication error.

Error responses

HTTP status	Response body	Cause
401	{"error": "API key required (X-API-Key header)"}	The X-API-Key header is missing
401	{"error": "Invalid API key"}	The key was provided but does not match any active key for your tenant
403	{"error": "User not a member of this tenant"}	The Bearer token is valid but the user does not belong to the target organization

Tip

If you receive a 401 Invalid API key error and you are sure the key is correct, check that you are sending the request to your organization’s subdomain, not a generic base URL. The API validates the key against the tenant derived from the subdomain.

Quick reference

Header	Value	Used for
X-API-Key	Your API key from the dashboard	Consent, banners, user rights endpoints
Authorization	Bearer <token>	Consent link management endpoints