Make API requests | Mux

Make API requests

This guide shows how to authenticate requests to the Mux API with an access token. Use it when you set up a server, a serverless function, or a script that calls Mux.

In this guide:

The Mux API is a REST API that you call from a trusted server environment. This guide shows how to authenticate requests, set token permissions, and work with pagination and rate limits. Read it when you connect your backend to Mux for the first time, or when you debug a failed request.

HTTP basic auth

Term Description
Token ID access token ID, the "username" in HTTP basic auth
Token secret access 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. 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: Access Token Settings.

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 be 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.

Example of authenticating a request with cURL

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:

  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, the library is handling the base64 encoding and setting the header value internally.

Access token permissions

Full Permissions

If you're just getting started with Mux Video, use Read and Write.

If you are creating or modifying resources with Mux Video then you need Read and Write permissions. This includes:

If you need to create signed tokens for secure video playback, your access token needs System write permissions. Learn more about secure video playback and signing keysAPI.

If your code is not creating anything and only making GET requests, you can restrict the access token to Read only.

CORS and client side API requests

Mux API endpoints do not have CORS headers. Although making API requests directly from a browser would be convenient, it leaves a massive security hole in your application since client side code would contain your API keys.

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 should be:

  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.

Using Mux with serverless functions

Serverless functions are great for adding secure server-side code to a client-heavy application. Examples include:

API pagination

Our list endpoints do not return every single relevant record to offer the best performance. Pagination parameters help navigate through the list.

Page/limit pagination

Parameter Default Maximum Description
page 1 None The page number to return.
limit 10 100 Number of records to return per page.

Cursor pagination

In addition to page/limit, cursor pagination is a more efficient and reliable way of paginating through large collections.

API rate limits

The Mux API implements rate limits to protect against overwhelming requests and ensure stability. Each environment also counts toward an organization-wide cap.

Checking your current limit status

Every API response includes headers you can use to monitor consumption: