Mux logo - video home
Docs
  • Introduction to Data
  • Track your video engagement and performance
  • Make API requests
  • Set up alerts
  • Make your data actionable with metadata
  • Track autoplaying videos
  • Extend Data with custom metadata
  • Track CDN for request metrics
  • See how many people are watching
  • Build a custom integration
  • Understand metric definitions
  • Export raw video view data
  • Ensure privacy compliance
  • Mux Data FAQs
Mux.comLog in
Mux logo - video home
Docs
GuidesAPI ReferenceChangelog

Make API requests

In this guide you will learn how to work with Mux's API through http requests.

In this guide:

HTTP basic auth

HTTP basic auth

Mux uses HTTP basic auth with your access token to authenticate requests.

Access token permissions

Access token permissions

Configure the necessary permissions for your access tokens.

CORS and client side API requests

CORS and client side API requests

Mux APIs are meant to be requested from a trusted server environment, not from clients directly.

API rate limits

API rate limits

Understand rate limits when accessing the Mux API.

Get started quickly with Postman

We recommend Postman as a way to easily explore and interact with our API.

If you're a Postman user, you can fork our officially supported Postman collection and add it to your workspace by clicking the button below.

Future updates and changes to our API specification will be synced with your fork automatically.

Run in Postman

HTTP basic auth

TermDescription
Token IDaccess token ID, the "username" in HTTP basic auth
Token secretaccess token secret, the "password" in HTTP basic auth

Every request to the API is authenticated via an Access Token, which includes the ID and the secret key. You can think of the Access Token’s ID as its username and secret as the password. Mux only stores a hash of the secret, not the secret itself. If you lose the secret key for your access token, Mux cannot recover it; you will have to create a new Access Token. If the secret key for an Access Token is leaked you should revoke that Access Token on the settings page: https://dashboard.mux.com/settings/access-tokens.

Note that in order to access the settings page for access tokens you must be an admin on the Mux organization.

API requests are authenticated via HTTP Basic Auth, where the username is the Access Token ID, and the password is the Access Token secret key. Due to the use of Basic Authentication and because doing so is just a Really Good Idea™, all API requests must made via HTTPS (to https://api.mux.com).

Watch out for mismatched tokens and environments

Access tokens are scoped to an environment, for example: a development token cannot be used in requests to production. Verify the intended environment when creating an access token.

This is an example of authenticating a request with cURL, which automatically handles HTTP Basic Auth. If you run this request yourself it will not work, you should replace the Access Token ID (44c819de-4add-4c9f-b2e9-384a0a71bede) and secret (INKxCoZ+cX6l1yrR6vqzYHVaeFEcqvZShznWM1U/No8KsV7h6Jxu1XXuTUQ91sdiGONK3H7NE7H) in this example with your own credentials.

curl https://api.mux.com/data/v1/filters \
  -H "Content-Type: application/json" \
  -u 44c819de-4add-4c9f-b2e9-384a0a71bede:INKxCoZ+cX6l1yrR6vqzYHVaeFEcqvZShznWM1U/No8KsV7h6Jxu1XXuTUQ91sdiGONK3H7NE7H 

HTTP basic auth works by base64 encoding the username and password in an Authorization header on the request.

Specifically, the header looks something like this:

'Authorization': 'Basic base64(MUX_TOKEN_ID:MUX_TOKEN_SECRET)' 
  1. The access token ID and secret are concatenated with a : and the string is base64 encoded.
  2. The value for the Authorization header is the string Basic plus a space followed by the base64 encoded result from Step 1.

In the cURL example above, the cURL library is taking care of the base64 encoding and setting the header value internally. The HTTP library you use in your server-side language will probably have something similar for handling basic auth. You should be able to pass in the username (Access Token ID) and password (Access Token secret) and the library will handle the details of formatting the header.

Access token permissions

Mux Data API endpoints only support GET requests, so Mux Data token permissions are read-only.

CORS and client side API requests

Mux API endpoints do not have CORS headers, which means if you try to call the Mux API from the browser you will get an error:

CORS Error in Browser

request has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

This is expected. Although making API requests directly from the browser or your mobile app would be convenient, it leaves a massive security hole in your application by the fact that your client side code would contain your API keys. Anyone who accesses your application would have the ability to steal your API credentials and make requests to Mux on your behalf. An attacker would be able to gain full data access control of your Mux account.

Mux API Credentials should never be stored in a client application. All Mux API calls should be made from a trusted server.

Instead of trying to make API requests from the client, the flow that your application should follow is:

  1. Client makes a request to your server
  2. Your server makes an authenticated API request to Mux
  3. Your server saves whatever it needs in your database
  4. Your server responds to the client with only the information that the client needs.

API rate limits

Mux Data implements a simple set of rate limits. Rate limits are set per account (not per environment). These rate limits exist to ensure that there's always Mux infrastructure available when our customers need it.

Exceeding the rate limit

When the rate limit threshold is exceeded, the API will return a HTTP status code 429.

Realtime Data API rate limits

Requests against the Realtime Data APIs are rate limited to a sustained 1 request per second (RPS) with the ability to burst above this for short periods of time.

Non-realtime Data API rate limits

Requests against the all other General Data APIs are rate limited to a sustained 5 request per second (RPS) with the ability to burst above this for short periods of time.

Was this page helpful?