Start here

Authentication & site setup

Use public keys for browser collection, private keys for server verification, and scoped sessions for workspace management.

On this page

Choose the right authentication

Surface	Authentication	Use
Browser endpoints	X-Site-Key	Public telemetry collection with an allowed Origin.
Server /verify endpoints	X-Site-Key + X-Secret-Key	Trusted backend scoring, fingerprinting, and challenges.
Workspace management	Authorization: Bearer <accessToken>	Manage sites, rules, webhooks, and SSO.
Incoming webhook	Bastion-Signature	Validate exact raw payload bytes with the webhook secret.

The SDKs add the scoring headers automatically. Public keys are intentionally public and cannot establish customer identity or a successful login. Never use a browser-only response to authorize payment or fulfillment.

Configure frontend origins

bash

curl -X PATCH 'https://api.bastionsecurity.io/api/sites/YOUR_SITE_ID' \
  -H "Authorization: Bearer $BASTION_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"allowedOrigins":["https://shop.example.com","http://localhost:3000"]}'

Origins are exact scheme, host, and optional port values, without paths. Set the complete desired list when updating it. Requests from a non-allowlisted browser Origin fail with 403. CORS is a browser access control; it does not replace private server authentication.

Rotate site keys

bash

curl -X POST 'https://api.bastionsecurity.io/api/sites/YOUR_SITE_ID/rotate-keys' \
  -H "Authorization: Bearer $BASTION_ACCESS_TOKEN"

The owner can rotate both public and server keys in Integration or through this endpoint. Existing keys stop working immediately. Update the backend environment and browser configuration together. Webhook signing secrets rotate separately in Webhooks; there is no automatic old-key overlap window.

Workspace access tokens

POST /api/auth/login with email and password returns user, accessToken, and refreshToken inside data. Use accessToken for management endpoints. Access tokens expire after one hour. A refresh token is returned, but the API currently has no refresh exchange endpoint: sign in again when the access token expires.

SAML sessions are scoped to one workspace. A scoped token cannot manage another tenant or account-wide settings. Site owner, analyst, and viewer permissions also apply to management operations. Prefer site-secret scoring authentication for application traffic, rather than a dashboard session.