API Security
HTTPS
All communication between clients and Percus services is over HTTPS. HTTP connections are not accepted. TLS termination is handled at the CloudFront and load balancer layers before traffic reaches application services.
Backoffice API authentication
The Backoffice API uses Bearer token authentication. The JWT session token issued by NextAuth.js is forwarded with every request. The backend validates the token and extracts the user's roles before processing any operation.
Requests with missing or invalid tokens receive 401 Unauthorized. Requests with valid tokens but insufficient role receive 403 Forbidden.
API credentials (programmatic access)
Projects that integrate the Percus Player programmatically use API credentials — a key/secret pair scoped to a single project.
| Property | Detail |
|---|---|
| Scope | Per project — one credential cannot access another project's resources |
| Key format | pk_... prefix (public key, safe to include in client-side config) |
| Secret format | sk_... prefix — returned once at creation, stored as a one-way hash |
| Rotation | POST /api/credentials/{id}/revoke — revoke and create a new credential |
| Who can manage | ProjectManager or OrganizationAdmin |
The secret is shown exactly once. If it is lost, create a new credential and revoke the old one.
Player postMessage security
The Percus Player runs inside a cross-origin <iframe> and communicates with the host page via the postMessage API. The following controls apply:
| Control | How it works |
|---|---|
| Origin allowlist | The player accepts commands only from origins in a configurable allowlist. Commands from unlisted origins are silently dropped. |
| Source validation | The SmartEmbed SDK validates that inbound messages originate from the injected iframe (event.source === iframe.contentWindow). Messages from other sources are ignored. |
| Target origin | In production, postMessage calls should be pinned to the known player domain rather than using "*". |
The host page is responsible for setting appropriate sandbox attributes on the iframe element.
Idempotency keys
Template upload endpoints accept an optional Idempotency-Key header. If a network failure causes an upload to be retried, supplying the same key prevents duplicate template creation.
Rate limiting
Rate limiting is applied at the CloudFront and API Gateway layers. Limits are configured per environment and per API surface. Specific thresholds are communicated during client onboarding.