Docs/Authentication

Authentication

The API authenticates with a team API key passed as a bearer token. Each key is scoped to a single team and environment.

API keys

Generate keys in Teams → API keys. A key is shown in full only once — only a SHA-256 hash is stored on our side. Pass it as a bearer token in the header shown below:

curl https://api.seeitlive.io/v1/sessions \
  -H "Authorization: Bearer sil_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Environments

Each key belongs to one of two environments, identified by its prefix:

Prefix	Environment	Use
`sil_live_`	Production	Real customer sessions.
`sil_test_`	Sandbox	Development and testing.

Sessions created with a key inherit that key's environment and team.

Securing a key

Each key can be restricted so a leaked key is useless from the wrong place:

Allowed sources — Restrict a key by IP, CIDR, or hostname — one per line. Hostnames are resolved via DNS and matched against the caller's IP. Add an inline label after # or ;, e.g. 1.2.3.4/24 # server 1.
Expiry — Give a key an expiry date. Once it passes, requests using that key are rejected.
Revoke — Disable a key instantly — in-flight requests start failing immediately.

Rotate leaked keys immediately

If a key is exposed, revoke it and restrict its replacement with an allowed sources list before distributing it again.

Request signing

Signing is opt-in and layers on top of key authentication — the Authorization: Bearer header is still required on every request. Enable, rotate, or disable it for a key from Team → API keys → the key → Security; enabling or rotating reveals the signing secret once, so store it immediately.

Once enabled, sign each request by computing HMAC_SHA256(signingSecret, "TIMESTAMP.METHOD.PATH.sha256hex(body)"), hex-encoded, where:

Variable	Description
`TIMESTAMP`	The unix timestamp in seconds — the same value sent in the `X-SeeItLive-Timestamp` header.
`METHOD`	The HTTP method, uppercase (e.g. POST).
`PATH`	The request path relative to the API version root — what you append to the base URL, e.g. `/sessions` or `/keys?teamId=x`. Not the full URL, and without the `/api/v1` prefix. Include the query string.
`sha256hex(body)`	Lowercase-hex SHA-256 of the exact request body bytes; the hash of an empty string when there's no body.

Send the signature and timestamp as headers on every signed request:

Header	Value
`X-SeeItLive-Signature`	`sha256=` followed by the hex-encoded signature.
`X-SeeItLive-Timestamp`	The same unix timestamp (seconds) used in the signature.

SIGNING_SECRET=your-signing-secret   # shown once when you enable signing
TS=$(date +%s)
BODY='{"channel":"demo"}'
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | sed 's/^.* //')
SIG=$(printf '%s' "$TS.POST./sessions.$BODY_HASH" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | sed 's/^.* //')
curl https://api.seeitlive.io/v1/sessions \
  -H "Authorization: Bearer sil_live_xxxxxxxx" \
  -H "X-SeeItLive-Timestamp: $TS" \
  -H "X-SeeItLive-Signature: sha256=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

300-second replay window

Requests are rejected if the timestamp is more than 300 seconds from the server's clock, or if the signature doesn't match.

Rate limits

The API allows 100 requests per minute per key. Session-creation and invite-delivery endpoints have tighter limits. Exceeding a limit returns 429 — see the full Errors reference for every status code the API can return.

Status	Meaning
`401`	Missing or invalid key.
`403`	Key not allowed from this IP or origin, or missing permission.
`402`	Plan limit reached (sessions, seats) — upgrade required.
`400`	Validation error.
`429`	Rate limit exceeded.

Getting started API keys