Authentication & device identity

Every embedding mode plugs into the same identifiers and the same three authentication layers. Understand these once and they apply everywhere — iframe, script tag, SDK, native, and raw REST.

Identifiers

Field	Shape	Where it appears
shortId	12-char URL-safe	Everywhere a polst is referenced externally
campaignId	UUID	Everywhere a campaign is referenced externally
brandSlug	URL-safe slug	Brand-scoped public endpoints (/brands/{slug}/...)

Internal UUIDs are never exposed on the public surface.

Authentication — three layers

1. Public read — anyone can fetch a polst, a campaign, their tallies, and a brand’s public feed. No credentials.
2. Device identity — anonymous voting uses X-Device-Id: <stable-uuid>, generated and persisted once per browser or app install. The backend creates a guest session keyed on it.
3. Trusted App (TAI) — brand-scoped operations (list own polsts, create, delete, analytics) require a short-lived access token obtained by exchanging an apiKeyId + apiKeySecret pair at POST /api/rest/v1/auth/token. Tokens carry scopes: view, vote, manage, analytics. Access tokens are 15 minutes; refresh tokens rotate on every use.

Every mode plugs into these same three layers.

Note

Voter identity on a vote request is either Authorization: Bearer <tai-access-token> or X-Device-Id: <uuid>. At least one is required.

Exchanging an API key for a token

The Trusted-App flow exchanges your API key for an access/refresh token pair:

Headers:
  X-API-Key-ID:     <apiKeyId>
  X-API-Key-Secret: <apiKeySecret>
Body:
  { "externalDeviceId": "optional-device-id", "scopes": ["manage", "analytics"] }

All subsequent requests use Authorization: Bearer <accessToken>. Refresh and revoke the token family via POST /auth/token/refresh and POST /auth/token/revoke.

See the REST API reference for the full request and response schemas of the auth endpoints, and Data shapes for what the authenticated endpoints return.