Authentication¶

VaultStream uses Bearer token authentication for all API access. Tokens are scoped, revocable, and tied to specific service accounts or user identities.

Token Types¶

Type	Prefix	Use Case	Lifetime
API Token	`vst_live_`	Server-to-server, automation	Until revoked
User JWT	`eyJ...`	Client-side, player embedding	24 hours
Session Token	`vst_ses_`	Web player sessions	2 hours idle

Creating API Tokens¶

Via the Partner Portal or programmatically:

POST /v1/auth/tokens
Authorization: Bearer <ADMIN_TOKEN>
Content-Type: application/json

{
  "name": "CI/CD Pipeline",
  "scopes": ["content:write", "content:read"],
  "expires_at": null
}

Response:

{
  "status": "ok",
  "data": {
    "id": "tok_abc123",
    "name": "CI/CD Pipeline",
    "token": "vst_live_a1b2c3d4e5f6...",
    "scopes": ["content:write", "content:read"],
    "created_at": "2026-07-04T12:00:00Z"
  }
}

Warning

The token value is shown only once. Store it securely — VaultStream cannot recover a lost token value.

Token Scopes¶

Scope	Access
`content:read`	List and retrieve content metadata
`content:write`	Upload, update, delete content
`admin:read`	Read admin settings, audit logs
`admin:write`	Modify admin settings, manage users
`analytics:read`	Access viewership metrics
`webhook:manage`	Create/edit/delete webhooks

Using Tokens¶

All requests include the token in the Authorization header:

curl -H "Authorization: Bearer vst_live_xxxx" \
  https://api.cyfr.technology/v1/content

import requests

headers = {"Authorization": f"Bearer {token}"}
resp = requests.get("https://api.cyfr.technology/v1/content", headers=headers)

const resp = await fetch("https://api.cyfr.technology/v1/content", {
  headers: { Authorization: `Bearer ${token}` }
});

User JWT (Player Embedding)¶

For client-side player embedding, generate a short-lived JWT for the viewing user:

POST /v1/auth/jwt
Authorization: Bearer <API_TOKEN>

{
  "user_id": "usr_xyz789",
  "content_id": "c_7a3b9f1d",
  "ttl_seconds": 86400
}

The resulting JWT is passed to the player:

VSPlayer.mount('#player', {
  contentId: 'c_7a3b9f1d',
  jwt: '<GENERATED_JWT>'
});

Token Revocation¶

DELETE /v1/auth/tokens/tok_abc123
Authorization: Bearer <ADMIN_TOKEN>

Revocation takes effect within 60 seconds globally.

Security Best Practices¶

Use separate tokens per service — Never share a token between production and staging
Scope tokens minimally — A content ingestion script needs content:write, not admin:write
Rotate tokens regularly — Revoke and regenerate tokens quarterly
Store tokens in a secrets manager — Never hardcode tokens in source code or config files
Monitor token usage — Review audit logs for unexpected token activity