Apps and keys

Applications

An application is a namespace. Streams, VOD assets, ads, recordings, and keys all belong to exactly one. A fresh install has default.

curl -b jar -X POST http://localhost:9001/api/v1/apps \
  -H 'content-type: application/json' -d '{"name":"acme-tv"}'

Creating an application needs the global token. An app-scoped token reaches only its own application, which is what makes it safe to hand to someone else.

Ingest security

Each application chooses how strictly publishing is controlled.

Mode	Who may publish	Stream name chosen by
Open	Anyone who knows the URL	The publisher
AppKey	Anyone holding the application’s shared key	The publisher
StreamKey	Only a holder of a registered stream key	The key itself

Open is the development default and is exactly as permissive as it sounds. Change it before the server is reachable from the internet.

StreamKey is the strongest, because the key selects the stream. A key that leaks can publish to its own stream and nothing else, and revoking it affects only that one.

A registered stream key is honoured in every mode, so tightening the mode later does not break encoders that already use keys. The shared application key works only in AppKey mode, deliberately: otherwise it would remain a master key that survived revoking an individual stream’s key.

Managing keys

# One key per encoder, so a single leak can be revoked alone
curl -b jar -X POST http://localhost:9001/api/v1/apps/acme-tv/stream-keys \
  -H 'content-type: application/json' -d '{"name":"studio-a"}'

curl -b jar http://localhost:9001/api/v1/apps/acme-tv/stream-keys

# Revoke immediately
curl -b jar -X DELETE http://localhost:9001/api/v1/apps/acme-tv/stream-keys/studio-a

# Or keep the name and replace the secret
curl -b jar -X POST \
  http://localhost:9001/api/v1/apps/acme-tv/stream-keys/studio-a/regenerate

Keys are 26 characters from an alphabet that omits look-alike glyphs, so they survive being read down a phone line. They are compared in constant time.

Accounts

Publish keys are for encoders. People get accounts, with roles, and an administrator manages them under /api/v1/users. An account can be limited to specific applications, which pairs well with app-scoped tokens when someone operates one channel and should not see the rest.