Skip to content
Szenera DeveloperDocs
Getting started › Orientation › How does a call flow through the platform?
Chapters

How does a call flow through the platform?

From the bearer header through the permission check to the response with a trace ID: the stations every call passes through.

4 minute readGetting startedUpdated: 10/25/2026

On this page

Before you start

For
Developers before the first call against the Szenera API
Prerequisite
none. The page explains what an API key sets in motion later

Every call passes through the same three stations: the platform recognizes the credential, selects the operation under /v1 and checks its permission, and then answers with JSON and the headers that apply everywhere. Anyone who knows these stations can read every error response at a glance.

Station 1: The credential in the bearer header

The platform recognizes from the prefix of the value in Authorization: Bearer … which kind of credential is present, with no further input from you:

Prefix Credential For whom
ak_ API key of an organization Machines: scripts, services, your integration
eyJ Session token from POST /v1/auth/login People in the portal. Valid for 15 minutes, then a refresh
oat_ Access token of a delegated access a third-party application on behalf of a person
opk_ Key of platform operations only the operator of the platform
rdr_ Renderer token the playback process of a paired device

At the edges you meet sct_ (a directory service under /scim/v2, nowhere else), inv_ (an invitation before the first sign-in), and dev_ (the first registration of a device). Devices in operation identify themselves with their certificate. For your integration, ak_… is the standard way: no expiry after a quarter of an hour, no refresh.

A value with an unknown prefix explicitly does not count as anonymous. It is rejected as an unusable credential with 401 Auth.Required, so a typo in the prefix becomes a 401 and not a misleading 404. A call without a header gets the same response, and a key with the right prefix but a truncated value gets 401 Auth.TokenMalformed.

Station 2: Route and permission check

Every route that Szenera itself controls lives under /v1, and the path is part of the contract. Only where a third-party standard dictates its address is the prefix absent (/oauth/…, /.well-known/…, /scim/v2/…). Then the platform checks, per operation, the permission that the reference names for it (for example playlist.list for GET /v1/playlists). An API key carries the fixed list of permissions from its creation. Devices, pairing and deleting displays, and key management stay reserved for user accounts. If the permission is missing, the answer is 403 Permission.Denied. Routes of platform operations answer a key of an organization with 403 Permission.OperatorOnly.

A call runs from the client through credential recognition, route, and permission check to the response. An unknown credential and a missing permission branch off into the error body

The error branch carries the same body as every error: code, message, traceId.

Station 3: The response and its headers

The platform speaks JSON. Four headers shape the exchange, three in the response and one in the request, wherever their condition is met:

Header When
X-Trace-Id always, the trace ID of this call
If-Match (request) when changing versioned resources (scenes, playlists, programs, roles, displays): the version you read goes along as If-Match, and the same number is in the response as ETag
Idempotent-Replay: true when a retry with the same Idempotency-Key received the stored response
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset only on throttled routes, above all sign-in, registration, and password reset

An error always comes in the same body: code in the form Area.Cause, message as a short text, and traceId with the prefix trc_. The HTTP status follows the area of the code: Auth.* → 401, Permission.* → 403, *.NotFound → 404, Conflict.* → 409, Validation.* → 422, RateLimit.* → 429.

What follows

  • Keys instead of sessions for machines. A session token expires after 15 minutes. A key ak_… does not.
  • Branch on code, never on message. The code is stable and part of the contract. The text may change.
  • Log the trace ID. X-Trace-Id and traceId are the same value, the one you give when you ask for help.
  • Give the key only the permissions your integration needs. A key that is too narrow shows up as a 403. A key that is too wide shows up as nothing.