Fundamentals

An Orilla integration moves a source through processing into an asset, then grants viewers access through playback IDs. Understanding those boundaries helps you choose the right identifier, wait for the right state, and keep management credentials out of the player.

Work in an organization and environment

An organization groups your team and its environments. An environment scopes the content and integration configuration your application works with. Select it in the dashboard before creating an API token or adding content.

A token belongs to an environment and carries permissions such as video:read and video:write. The SDK’s whoami() method returns its organization, environment, and permissions. Use that identity to check that your backend is connected to the intended workspace, especially when separating development from production.

Know which resource you have

Concept	What it represents	Use it for
Organization	A team and its environments	Membership and workspace administration
Environment	The scope for content, API tokens, and integration configuration	Separating application contexts
Upload	A direct-upload session that receives source bytes	Tracking transfer completion and finding its asset_id
Asset	A media item and its processing state, metadata, tracks, and outputs	Backend management through an asset ID
Playback ID	A public or signed access handle associated with an asset	Constructing player, HLS, and related media URLs
Signing key	A key whose private part authorizes signed playback	Issuing temporary viewer access from your backend

An asset ID and a playback ID are different identifiers. Retrieve and update an asset with its asset ID. Embed or stream it with a playback ID. An asset can have multiple playback IDs with different access policies; do not assume the first ID has the policy you need.

Upload completion is one stage

There are two common ways to provide a source:

1. Import a URL: assets.create accepts an HTTP(S) media URL and returns an asset. The server fetches the source and processes it asynchronously.
2. Upload a local file: create a direct-upload session, transfer the bytes, and follow the upload’s asset_id to the resulting asset.

For a URL import, the asset moves from preparing to ready or errored. Direct uploads have a separate lifecycle: waiting becomes asset_created when there is an asset to follow, or ends as cancelled, timed_out, or errored.

A completed transfer or an asset_created upload is not a ready asset. Retrieve the asset until its status is ready, or handle a verified video.asset.ready webhook. On errored, inspect the asset’s errors before deciding how to recover. Bound polling so a slow worker does not leave an application waiting indefinitely.

Tracks and downloadable renditions also have processing states. A ready asset does not mean that every separately requested track or download is ready.

The API quickstart includes bounded polling. URL imports and direct uploads describe each source path.

Separate management from watching

Your backend uses the environment token ID and secret to authenticate API requests. The SDK sends these as Basic authentication to the compatible API routes. Keep those credentials on the server; an iframe or browser player does not need them.

Playback authorization follows the selected playback ID:

• Public: the link grants access to anyone who has it while the playback ID remains active. Choose this deliberately for content intended to be public.
• Signed: your backend uses a signing key to issue temporary playback authorization. The client receives the resulting authorized URLs or tokens, while the private key stays on the server.

Creating an asset with a signed policy does not create a public link. Embedding its playback ID without the required authorization does not grant access. Likewise, knowing an asset ID does not replace management permissions.

Follow access control for signing, restrictions, and revocation. An expiration stops future authorized requests; it cannot retract content already received.

Choose the output for the task

Adaptive playback uses the HLS manifest at /stream/PLAYBACK_ID.m3u8. The player requests playlists and media segments for the available renditions. The hosted iframe at /embed/PLAYBACK_ID gives a page an Orilla player without installing a player package.

Downloads are separately generated MP4 or M4A outputs. Request the appropriate rendition and wait for its own ready state. A ready HLS stream does not guarantee a download exists.

Original access is another asset setting and lifecycle. Enabling temporary master access is distinct from requesting a processed download. Review the asset’s returned master status and URL rather than treating its HLS or download URL as the original.

The player guide covers iframe, React, and HTML integration. Formats and limits explain output boundaries; the API reference describes the resources.

Observe the right signal

Processing status answers whether content is ready. Playback analytics describe reported viewing events when collection is enabled. Usage describes observed storage, delivery, and ingest. Each has its own scope and coverage; missing data is not automatically zero.

Continue with the API quickstart to create a first asset, wait for processing, and embed it.