Skip to content

API authentication

Introduction

HeapStream uses HTTP Basic Auth: use your API key's id as the username and its password as the password.

Requests with incorrect credentials receive a 401 Unauthorized response with a JSON body describing the error.

API key protection

Call the HeapStream API from your own server-side code only, so your credentials never reach the client.

Keeping keys safe

  • Keep keys in environment variables or in a config file outside your application's source tree. Keys hardcoded in source have a way of ending up in version control and in code you share.
  • Check code for stray keys before publishing it.
  • Delete keys you no longer use.
  • Give each backend system its own key pair. If one leaks, you can delete it without breaking the others.

Accessing API keys

Find your API key id and password in the dashboard, where you can also manage separate keys for different applications.

Who can call what

A key acts as the user it belongs to, with the same access that user has in the dashboard. On each project you are either its owner or a member with one of three roles, set by whoever manages the project's members:

Role May
Owner Everything, including the project's members, its signing keys and deleting it.
Manager Everything an Owner may, except members, signing keys and deleting the project.
Editor View, upload and edit videos (details, captions, folders, delete), manage live streams, view statistics.
Viewer View videos, live streams (without the RTMP server URL and stream key, which live.manage reads) and statistics. Viewers do not take up a seat.

Every operation in the API reference ⧉ declares the permission it needs as x-permission in the OpenAPI spec: video.view, video.upload, video.edit, live.view, live.manage, analytics.view, settings.manage (project settings, players, encoding profiles, watermarks, webhooks), keys.manage, members.manage, project.delete. The three operations without one (project list, project create, account bandwidth) concern your own account rather than a project.

  • A project you own or belong to: the operations your role's permissions cover. One your role lacks answers 403 with the error code permission_denied and the permission's name in the message.
  • Any other project: 401 with not_project_owner.

Projects you belong to appear in your project list (GET /api/v1/project), the same list the dashboard shows. Storage and usage on a project are always billed to its owner, whoever uploads. If the owner's account is suspended, every request to their projects answers 403 with account_suspended, for the owner and members alike. An account suspended by HeapStream cannot call the API at all, on any project.

Basic Auth request example

For ApiKey.id 3275020786116592843 and ApiKey.password uO_wTq_QqjKTtSeya2tCZx6ja6RVMqXU, the authenticated request is:

curl --header 'Authorization: Basic MzI3NTAyMDc4NjExNjU5Mjg0Mzp1T193VHFfUXFqS1R0U2V5YTJ0Q1p4NmphNlJWTXFYVQ==' https://staging.heapstream.com/api/v1/project/