Skip to content
FrameWorks Docs
Blog

Access and playback

GraphQL schema reference · API guide · SDKs

Playback signing keys, developer tokens, playback policy, and viewer endpoint resolution.

Types used by more than one domain are on Shared types.

Queries

Section titled “Queries”

Query.developerTokensConnection

Section titled “Query.developerTokensConnection”

List API tokens for programmatic access. Used to authenticate requests to the Developer API.

developerTokensConnection(
  page: ConnectionInput
): DeveloperTokensConnection!

Returns: DeveloperTokensConnection! (DeveloperTokensConnection)

Arguments

SDK

OperationTypeScriptGoPython
ListDeveloperTokensListDeveloperTokensDocumentListDeveloperTokenslist_developer_tokens

Query.resolveViewerEndpoint

Section titled “Query.resolveViewerEndpoint”

Resolve a playback ID to viewer endpoints (HLS, DASH, etc.). Used by players to get the optimal CDN endpoint for playback.

resolveViewerEndpoint(
  contentId: String!
  protocol: MediaViewerProtocol
): ViewerEndpointResponse

Returns: ViewerEndpointResponse (ViewerEndpointResponse)

Arguments

  • contentId: String! — Playback ID for live streams or VOD uploads, or artifact playback ID for clips/DVR.
  • protocol: MediaViewerProtocol (MediaViewerProtocol) — Optional playback constraint. A different format is never substituted. Omit to select a node with any playable Mist output and receive its full catalog.

SDK

OperationTypeScriptGoPython
ResolveViewerEndpointResolveViewerEndpointDocumentResolveViewerEndpointresolve_viewer_endpoint

Query.signingKey

Section titled “Query.signingKey”

Get a single playback signing key by ID. Tenant-scoped.

signingKey(
  id: ID!
): SigningKey

Returns: SigningKey (SigningKey)

Arguments

  • id: ID!

SDK

OperationTypeScriptGoPython
GetSigningKeyGetSigningKeyDocumentGetSigningKeyget_signing_key

Query.signingKeysConnection

Section titled “Query.signingKeysConnection”

List the tenant’s playback signing keys with optional status filter.

signingKeysConnection(
  status: String
  page: ConnectionInput
): SigningKeysConnection!

Returns: SigningKeysConnection! (SigningKeysConnection)

Arguments

  • status: String — Filter by status: ‘active’ or ‘revoked’. Empty = all.
  • page: ConnectionInput (ConnectionInput)

SDK

OperationTypeScriptGoPython
ListSigningKeysListSigningKeysDocumentListSigningKeyslist_signing_keys

Mutations

Section titled “Mutations”

Mutation.createDeveloperToken

Section titled “Mutation.createDeveloperToken”

Create a new API token for programmatic access.

createDeveloperToken(
  input: CreateDeveloperTokenInput!
): CreateDeveloperTokenResult!

Returns: CreateDeveloperTokenResult! (CreateDeveloperTokenResult)

Arguments

SDK

OperationTypeScriptGoPython
CreateDeveloperTokenCreateDeveloperTokenDocumentCreateDeveloperTokencreate_developer_token

Mutation.createSigningKey

Section titled “Mutation.createSigningKey”

Generate a new ES256 playback signing keypair. The private key is returned ONCE in the response and never stored or returned again — capture it. Up to 10 active keys per tenant; revoke before re-creating.

createSigningKey(
  input: CreateSigningKeyInput!
): CreateSigningKeyResult!

Returns: CreateSigningKeyResult! (CreateSigningKeyResult)

Arguments

SDK

OperationTypeScriptGoPython
CreateSigningKeyCreateSigningKeyDocumentCreateSigningKeycreate_signing_key

Mutation.revokeDeveloperToken

Section titled “Mutation.revokeDeveloperToken”

Revoke an API token.

revokeDeveloperToken(
  id: ID!
): RevokeDeveloperTokenResult!

Returns: RevokeDeveloperTokenResult! (RevokeDeveloperTokenResult)

Arguments

  • id: ID! — The token ID to revoke.

SDK

OperationTypeScriptGoPython
RevokeDeveloperTokenRevokeDeveloperTokenDocumentRevokeDeveloperTokenrevoke_developer_token

Mutation.revokeSigningKey

Section titled “Mutation.revokeSigningKey”

Mark an active signing key as revoked. Triggers session re-evaluation across the tenant’s protected playback objects: viewers with valid auth continue (possibly with a brief reconnect), revoked viewers are denied.

revokeSigningKey(
  id: ID!
): RevokeSigningKeyResult!

Returns: RevokeSigningKeyResult! (RevokeSigningKeyResult)

Arguments

  • id: ID!

SDK

OperationTypeScriptGoPython
RevokeSigningKeyRevokeSigningKeyDocumentRevokeSigningKeyrevoke_signing_key

Mutation.setPlaybackPolicy

Section titled “Mutation.setPlaybackPolicy”

Set or clear the playback access policy on a stream, VOD asset, or clip. Exactly one of streamId / vodAssetId / clipId must be set in the input. Webhook secrets are write-only on input and never returned in queries. Mutating a policy invalidates Foghorn caches and re-runs USER_NEW for affected sessions; valid viewers continue, invalid ones are denied.

setPlaybackPolicy(
  input: SetPlaybackPolicyInput!
): SetPlaybackPolicyResult!

Returns: SetPlaybackPolicyResult! (SetPlaybackPolicyResult)

Arguments

SDK

OperationTypeScriptGoPython
SetPlaybackPolicySetPlaybackPolicyDocumentSetPlaybackPolicyset_playback_policy

Mutation.testPlaybackAccess

Section titled “Mutation.testPlaybackAccess”

Run the same evaluator the live USER_NEW path uses against a caller- supplied JWT (or webhook test request) without registering a viewer session. Mutation, not query, because webhook mode (fireWebhook=true) fires a real outbound HTTPS request to the customer URL. Tenant ownership of the playback target is validated server-side.

testPlaybackAccess(
  input: TestPlaybackAccessInput!
): TestPlaybackAccessResult!

Returns: TestPlaybackAccessResult! (TestPlaybackAccessResult)

Arguments

SDK

OperationTypeScriptGoPython
TestPlaybackAccessTestPlaybackAccessDocumentTestPlaybackAccesstest_playback_access

Types

Section titled “Types”

CreateDeveloperTokenInput

Section titled “CreateDeveloperTokenInput”

input_object

Input for creating a developer API token.

  • name: String! — Human-readable name for the token.
  • permissions: String — Comma-separated permission scopes in resource:action form (streams:read, streams:write, analytics:read, etc.).
  • expiresIn: Int — Days until expiration, 1-3650 (null = non-expiring).

CreateDeveloperTokenResult

Section titled “CreateDeveloperTokenResult”

union

CreateSigningKeyInput

Section titled “CreateSigningKeyInput”

input_object

  • name: String! — Display label for the key (e.g. ‘staging’, ‘rotation-2026-q2’).

CreateSigningKeyResult

Section titled “CreateSigningKeyResult”

union

CreateSigningKeySuccess

Section titled “CreateSigningKeySuccess”

object

Returned exactly once on createSigningKey. Capture privateKeyPem before the response is discarded — FrameWorks does not store it and cannot return it again. Lose the private key, revoke and create a new one.

  • signingKey: SigningKey! (SigningKey)
  • privateKeyPem: String! — ES256 private key in PEM format. Shown ONCE; never stored, never logged.

DeveloperToken

Section titled “DeveloperToken”

object

An API token for programmatic access to the GraphQL API. Tokens have scoped permissions and optional expiration.

  • id: ID! — Unique token identifier.
  • tokenName: String! — Human-readable name for the token.
  • tokenValue: String — The secret token value (only returned on creation, null thereafter).
  • permissions: [String!]! — List of granted permission scopes (streams:read, streams:write, etc.).
  • status: String! — Token status (active, revoked, expired).
  • lastUsedAt: Time (Time) — When the token was last used for API access.
  • expiresAt: Time (Time) — When the token expires (null for non-expiring).
  • createdAt: Time (Time) — When the token was created.

DeveloperTokenEdge

Section titled “DeveloperTokenEdge”

object

DeveloperTokensConnection

Section titled “DeveloperTokensConnection”

object

MediaViewerProtocol

Section titled “MediaViewerProtocol”

enum

Playback format required when selecting and preparing a viewer destination.

  • WEBRTC
  • WHEP
  • HLS
  • DASH
  • HLS_CMAF
  • MEWS
  • MEWS_WEBM
  • MP4
  • WEBM
  • MKV
  • TS
  • AAC
  • H264
  • H264_WS
  • RAW_WS
  • JSON_WS
  • FLV
  • HDS
  • SMOOTHSTREAMING
  • SDP
  • MIST_HTML
  • RTMP
  • RTSP
  • SRT
  • DTSC

PlaybackAccessDecision

Section titled “PlaybackAccessDecision”

object

Structured result of a dry-run policy evaluation. Mirrors Foghorn’s PlaybackDecision struct.

  • allowed: Boolean!
  • policyType: String! — Resolved policy type: ‘public’ | ‘jwt’ | ‘webhook’ | ” when no policy was found.
  • reason: String — Empty on allow; deny reason token (e.g. ‘jwt-expired’, ‘webhook-deny-403’) otherwise.
  • detail: String — Free-form context for the operator (verifier error string, HTTP status as text).
  • kid: String — JWT key ID claimed by the token (extracted before verification).
  • claimsJson: String — JSON-encoded JWT claims map. On allow, the verified claims. On deny, an unverified parse of the payload — useful for diagnosing aud / required- claim mismatches but never trustworthy as an auth signal.
  • webhookStatus: Int — HTTP status code from the customer webhook (0 if no call was made).
  • webhookLatencyMs: Int — End-to-end RTT for the webhook call in milliseconds (0 if no call was made).
  • resolvedInternalName: String — Internal MistServer name the evaluator resolved against. Always populated when a target was found.

PlaybackInstance

Section titled “PlaybackInstance”

object

  • nodeId: String!
  • viewers: Int!
  • bufferState: String
  • bytesUp: Float
  • bytesDown: Float
  • totalConnections: Int
  • inputs: Int
  • lastUpdate: Time (Time)

PlaybackJwtClaimRequirementInput

Section titled “PlaybackJwtClaimRequirementInput”

input_object

  • name: String!
  • jsonValue: String! — JSON-encoded expected value (e.g. "pro", true, 42).

PlaybackJwtPolicyInput

Section titled “PlaybackJwtPolicyInput”

input_object

  • allowedKids: [String!] — Allowed signing key IDs. Empty = any active tenant key. Blank IDs are rejected.
  • requiredAudience: [String!] — If set, the viewer JWT’s aud claim must contain at least one of these.
  • requiredClaimsJson: [PlaybackJwtClaimRequirementInput!] (PlaybackJwtClaimRequirementInput) — Required claim constraints. Each entry’s value is JSON-encoded for type flexibility.

PlaybackMetadata

Section titled “PlaybackMetadata”

object

  • status: String!
  • isLive: Boolean!
  • viewers: Int!
  • bufferState: String
  • tracks: [PlaybackTrack!] (PlaybackTrack)
  • protocolHints: [String!]
  • instances: [PlaybackInstance!] (PlaybackInstance)
  • dvrStatus: String
  • dvrSourceUri: String
  • contentId: String!
  • contentType: String!
  • title: String
  • description: String
  • durationSeconds: Int
  • recordingSizeBytes: Float
  • clipSource: String
  • createdAt: Time (Time)
  • thumbnailAssets: ThumbnailAssets (ThumbnailAssets)
  • telemetryToken: String — Short-lived signed token binding the resolved serving endpoint. The player echoes it on its boot-telemetry beacon so Bridge can trust cluster attribution. Infrastructure attribution only — carries no viewer identity.

PlaybackPolicyInput

Section titled “PlaybackPolicyInput”

input_object

  • type: PlaybackPolicyType! (PlaybackPolicyType)
  • jwt: PlaybackJwtPolicyInput (PlaybackJwtPolicyInput) — Required when type == JWT.
  • webhook: PlaybackWebhookPolicyInput (PlaybackWebhookPolicyInput) — Required when type == WEBHOOK.
  • allowedOrigins: [String!] — JWT and WEBHOOK only: sites allowed to embed the content, each * or scheme://host[:port] (at most 50). Omit or empty for no restriction.

PlaybackTrack

Section titled “PlaybackTrack”

object

  • type: String!
  • codec: String!
  • bitrateKbps: Int!
  • width: Int!
  • height: Int!
  • channels: Int!
  • sampleRate: Int!

PlaybackWebhookPolicyInput

Section titled “PlaybackWebhookPolicyInput”

input_object

  • url: String! — https URL FrameWorks will POST to on each viewer connect.
  • secret: String — HMAC-SHA256 secret used to sign outbound webhook bodies. Write-only: persisted via field-level encryption and never returned in queries. Required when creating a webhook policy. Omit when updating an existing webhook policy to keep the currently configured secret.
  • timeoutMs: Int — Outbound POST timeout in milliseconds. Server caps at 10000; default 5000.
  • context: JSON (JSON) — A JSON object (at most 4 KiB) sent as context in every access request, e.g. {"courseId": "algebra-101"}, so the endpoint can decide without its own lookup.

RevokeDeveloperTokenResult

Section titled “RevokeDeveloperTokenResult”

union

RevokeSigningKeyResult

Section titled “RevokeSigningKeyResult”

union

SetPlaybackPolicyInput

Section titled “SetPlaybackPolicyInput”

input_object

  • streamId: ID — Exactly one of streamId, vodAssetId, or clipId must be provided.
  • vodAssetId: ID
  • clipId: ID
  • policy: PlaybackPolicyInput! (PlaybackPolicyInput)

SetPlaybackPolicyResult

Section titled “SetPlaybackPolicyResult”

union

SigningKey

Section titled “SigningKey”

object

A customer-managed signing key for issuing viewer playback JWTs. The private key is returned exactly once at creation time (in CreateSigningKeySuccess); FrameWorks stores only the public key. Up to 10 active keys per tenant.

Implements Node.

  • id: ID!
  • kid: String! — Short ID embedded in JWT header (kid) for fast key lookup.
  • name: String! — Customer-supplied label.
  • algorithm: SigningKeyAlgorithm! (SigningKeyAlgorithm) — Algorithm — ES256 only for v1.
  • publicKeyPem: String! — Public key in PEM format. The private key is never stored.
  • status: SigningKeyStatus! (SigningKeyStatus) — Lifecycle status.
  • createdAt: Time! (Time)
  • lastUsedAt: Time (Time) — Last time a JWT signed by this key successfully verified at playback.
  • revokedAt: Time (Time) — When the key was revoked (null if active).

SigningKeyAlgorithm

Section titled “SigningKeyAlgorithm”

enum

Algorithm used to sign viewer playback JWTs. ES256 only for v1.

  • ES256

SigningKeyEdge

Section titled “SigningKeyEdge”

object

SigningKeyStatus

Section titled “SigningKeyStatus”

enum

Lifecycle status of a signing key.

  • ACTIVE
  • REVOKED

SigningKeysConnection

Section titled “SigningKeysConnection”

object

TestPlaybackAccessInput

Section titled “TestPlaybackAccessInput”

input_object

Inputs for testPlaybackAccess. Exactly one of playbackId / internalName must be set (the server rejects both-set and neither-set). viewerToken is required for JWT policies and is forwarded to the webhook payload for webhook policies. fireWebhook gates a real outbound HTTPS call to the customer URL. That call uses the same SSRF-hardened evaluator path as live viewer admission, and customer endpoints may log, rate-limit, or trigger side effects from the test request. When playbackId is supplied, the server resolves the canonical internalName before invoking the evaluator so webhook payloads carry the same streamName the live USER_NEW path would.

  • playbackId: String
  • internalName: String
  • viewerToken: String — JWT to test (required for type=jwt; passed through in the webhook payload for type=webhook).
  • viewerIp: String
  • requestUrl: String
  • connector: String
  • sessionId: String
  • fireWebhook: Boolean — Webhook policies only: when true, Foghorn will POST to the configured customer URL with an HMAC-signed payload (same path the live evaluator uses). When false, the evaluator returns reason=“webhook-test-skipped” without making the call so operators can inspect the resolved policy without side effects.
  • origin: String — Origin header to test the policy’s allowed origins against.
  • referer: String — Referer header, used when origin is empty.

TestPlaybackAccessResult

Section titled “TestPlaybackAccessResult”

union

ViewerEndpoint

Section titled “ViewerEndpoint”

object

  • nodeId: String!
  • baseUrl: String!
  • protocol: String!
  • url: String!
  • geoDistance: Float
  • loadScore: Float
  • outputs: JSON (JSON)

ViewerEndpointResponse

Section titled “ViewerEndpointResponse”

object