Service: Common Access Token Validator - EyevinnOSC/community GitHub Wiki

Common Access Token Validator

Common Access Token Validator (serviceId eyevinn-cat-validate, service page) validates CTA-5007 Common Access Tokens (CAT). CAT is a lightweight, interoperable bearer token standard for content access control in streaming workflows. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT.

What it can do

  • Expose a REST endpoint that your origin or CDN calls to verify a CAT token before granting access to protected media.
  • Verify tokens against HMAC shared secrets or public keys from an asymmetric pair.
  • Optionally use Redis (for example Valkey) for token caching and revocation before expiry.
  • Optionally log analytics and audits to ClickHouse.

Creating an instance

  1. Create a service secret holding your base64-encoded signing key(s) with create-service-secret (serviceId: "eyevinn-cat-validate", name keys).
  2. Optionally create a Valkey (valkey-io-valkey) instance first if you want revocation support, and confirm it is running.
  3. Create the instance with create-service-instance using serviceId: "eyevinn-cat-validate". The instance name must be alphanumeric and at most 20 characters.
{
  "name": "myvalidator",
  "Keys": "{{secrets.keys}}",
  "Issuer": "https://auth.example.com",
  "RedisUrl": "{{secrets.redisurl}}",
  "ClickHouseUrl": "http://<clickhouse-host>:8123"
}

Only name and Keys are required. Wait for the instance with wait-for-service-ready or get-instance-status, then read its URL with describe-service-instance.

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only; on OSC at most 20 characters.
Keys Yes string Signing key(s) used to verify tokens, base64-encoded (HMAC shared secret or public key). Store as a service secret and pass as {{secrets.keys}}.
Issuer No string Expected token issuer claim, for example https://auth.example.com.
RedisUrl No string, sensitive Redis or Valkey connection URL used for token revocation, for example redis://<host>:6379. Store as a service secret if it contains credentials.
ClickHouseUrl No string ClickHouse URL used for analytics and audit logging, for example http://<host>:8123.

A {{secrets.NAME}} reference must be the whole field value. Overwriting a secret does not restart a running instance.

Using the instance

Send a GET request to the /validate path with the token in the Authorization header:

curl -H "Authorization: Bearer <your-cat-token>" \
  https://<instance-url>/validate

A 200 OK response means the token is valid. A 401 means it is invalid or expired.

Point your streaming origin's token check at the validator URL. The validator is stateless by default; set RedisUrl if you need to revoke tokens before they expire.

OSC CLI example:

npx -y @osaas/cli create eyevinn-cat-validate myvalidator \
  -o Keys="{{secrets.keys}}" \
  -o Issuer="https://auth.example.com"

Resources

⚠️ **GitHub.com Fallback** ⚠️