Skip to main content

Authentication & Security

This page consolidates every authentication and security control across the Prezent platform into one reference: how each surface authenticates, how API keys are scoped to least privilege, and the transport- and payload-integrity guarantees you can build on.

If you just want to make your first call, start with Getting Started → Authentication. This page is the deeper, security-focused companion.

Auth model by surface​

Prezent exposes several surfaces. They share one credential family (the Prezent API key) but differ in how that credential reaches the server.

SurfaceAuth mechanism
Platform API (api.prezent.ai)API key as Bearer token — Authorization: Bearer <api_key>
Hosted MCP (mcp.myprezent.com)OAuth 2.1 authorization code + PKCE; the server exchanges the resulting token for your Prezent API key server-side
Local MCP (stdio server)Bearer — API key supplied via the PRESENTATION_API_TOKEN environment variable
SCIM (/api/v1/scim/*)Bearer (RFC 7644 contract) — Authorization: Bearer <api_key>

A few clarifications worth calling out explicitly:

  • SCIM uses Bearer, not OAuth. The SCIM User Management API follows the RFC 7644 protocol contract, but it authenticates with the same Bearer API key as the rest of the platform — there is no separate OAuth flow for SCIM. See SCIM → Authentication.
  • Only the Hosted MCP surface uses OAuth. OAuth 2.1 (authorization code + PKCE) is how Claude.ai and other remote MCP clients obtain a token without ever handling your raw API key; the hosted server exchanges that token for your API key behind the scenes, so the key never leaves Prezent infrastructure. Details in Agents & MCP → Authentication.

Bearer authentication​

Every Platform API request carries the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
  • API keys are issued by your Customer Success Manager. Self-service key generation is not currently supported.
  • The API authenticates on the Authorization: Bearer header only — the AWS x-api-key header is not accepted.
  • Keys may carry an expiry_date and a status. A request made with an expired key is rejected with 401 EXPIRED_API_KEY, and the key's status is flipped to expired.
  • API keys are masked after generation. You can download and view a key exactly once at issue time; afterward it cannot be retrieved again, so store it securely.

Scoped API keys & least-privilege permissions​

Every Prezent API key is a least-privilege, per-endpoint scoped token. It carries an explicit server-side allow-list of permitted API paths, not blanket account access. A request to any path outside the key's allow-list returns 404 ENDPOINT_NOT_FOUND — the same response as a non-existent route, so an out-of-scope path is not even distinguishable from one that does not exist. Scope is enforced on every request, after the key is authenticated and before any handler runs.

Path patterns can include {param} placeholders (for example /api/v1/template-conversions/{callback_id}/download), so a scope covers a resource family without enumerating every id.

Scope profiles​

A key is provisioned for exactly the surface an integration needs. Each profile below is simply a named set of permitted paths — a key can be scoped to any one of them, a combination, or down to a single endpoint:

ProfilePermitted paths (example)Use case
Generation/api/v1/autogenerations, /api/v1/autogenerations/{callback_id}, /api/v1/autogenerations/{callback_id}/downloads, /api/v1/autogenerations/{callback_id}/regenerationsCreate decks and fetch results
Template conversion/api/v1/template-conversions, /api/v2/template-converter/status/{callback_id}, /api/v1/template-conversions/{callback_id}/downloadApply a brand template and download
Audiences (read-only)/api/v1/audiences, /api/v1/audiences/searchList and search audience profiles
Themes & templates (read-only)/api/v1/themes, /api/v1/templatesDiscover brand themes/templates
Webhook management/api/v1/webhook-subscriptions, /api/v1/webhook-subscriptions/{id}, /api/v1/webhook-subscriptions/{id}/rotate-secret, /api/v1/webhook-subscriptions/{id}/testManage event subscriptions
SCIM provisioning/api/v1/scim/*User provisioning (RFC 7644)

A leaked or misused key can only ever reach the endpoints it was issued for — an agent never holds more authority than its narrowest task needs.

How scopes are provisioned​

  • Scopes are provisioned by Prezent, per key, to match your integration. They are server-side path allow-lists — not OAuth scope strings, not token claims, and not self-service.
  • To issue a key or change its scope, contact your Customer Success Manager. Keys are least-privilege by default: request only the paths an integration actually needs.
  • Use a separate, narrowly-scoped key per integration and per environment so each can be monitored and revoked independently.

Requesting a scoped key​

Give your CSM the exact scope so the key is provisioned minimally:

Integration:  <name, e.g. "marketing-deck-bot">
Environment:  <production | UAT | development>
Scope:        <a profile above, or an explicit list of permitted paths>
Expiry:       <optional expiry date>

Because scope enforcement returns 404, treat an unexpected 404 ENDPOINT_NOT_FOUND on a known-good path as a possible scope problem, not just a typo.

API key hygiene​

Treat API keys as long-lived secrets equivalent to a password.

  • Store server-side only. Keep keys in a secrets manager or server-side environment variable. Never embed an API key in client-side code (browser JavaScript, mobile apps, public repos) where it can be extracted.
  • Never commit or log keys. Keep keys out of source control, CI logs, error trackers, and analytics. Scrub Authorization headers from any request logging.
  • Use separate keys per environment. Issue distinct keys for development, staging/UAT, and production so you can scope, monitor, and revoke them independently. The platform exposes separate hosts per environment (see Base URL).
  • Rotate on exposure. If a key is exposed, contact your Customer Success Manager to have it rotated and the old key revoked.
  • Scope down. Request keys scoped to only the endpoints an integration needs (see Scoped API keys & permissions).

Webhook signing secrets follow the whsec_ prefix convention (see Payload integrity). Like API keys, a webhook secret is shown once at creation and is masked on subsequent reads.

Transport security​

  • All Prezent API traffic is served exclusively over HTTPS. Every published environment host — production (api.prezent.ai), UAT, and development — is an https:// endpoint. There is no plaintext-HTTP host.
  • Webhook delivery targets must also be HTTPS. When you register a webhook subscription, an http:// target URL is rejected outright with 400 INVALID_URL_SCHEME, and targets that resolve to private, loopback, link-local, or metadata-service addresses are rejected to prevent SSRF. See Webhooks → URL requirements.

Payload integrity (webhook signing)​

When Prezent pushes events to your endpoint, every delivery is signed so you can prove it came from Prezent and was not tampered with in transit.

  • Each subscription is issued an HMAC secret (prefix whsec_), returned once at creation; subsequent reads expose only the secret_prefix.
  • Every delivery carries an X-Prezent-Signature: t=<unix>,v1=<hex> header. The v1 value is an HMAC-SHA256 of "{timestamp}.{raw_body}" keyed on your secret (a Stripe-compatible scheme).
  • Verify with a constant-time comparison and reject deliveries whose timestamp is outside a small tolerance (we recommend 5 minutes) to defeat replay of an intercepted payload.

Full verification walkthrough with cURL, Python, and Node.js examples: Webhooks → Verify the signature.

See also​