Authentication

The 3Play Media API uses API keys to authenticate requests. You can manage your Admin and Project API keys on the API Access Management page. API keys have one of the following access levels:

• Admin: Manage other API keys, users, and projects.
• Project: Manage files, transcripts, audio descriptions, and live ASRs. Place orders.
• Observer: Read-only access to files, transcripts, audio descriptions, etc., including IDs and metadata.

Once you have an API key, you can test your access by issuing a GET request to the /v3/authenticate endpoint.

Signed Authentication

For an added layer of security, signed authentication adds an expiring signature to requests, which is generated using an API secret key that is never exposed unless you request it. Please file a support ticket to set up signed authentication for your account if you want this added security. Support will need to flip a boolean switch on your account for this to work.

Once your account is set up to require signed requests, all standard workflow and admin requests from any API key in your account are required to include signature and signature_expires parameters.

signature_expires: Time since epoch, in seconds, after which the signature is considered invalid. This can be any value of your chosing.
signature: A SHA-256 hash computed using the method outlined below.
To compute your request signature:

Join the following strings with the | character

1. Request path (starting from /v3)
2. Request method, in all caps
3. Request querystring with parameters alphabetized, excluding signature but including signature_expires

• Compute the SHA-256 hash of the string above. Encode the result as a Base-64 string. (Use RFC4648, i.e. without line feeds.) The result is your request signature.
• Remember to URL-encode your signature in your request if you are using a low-level tool such as curl.

As an example, let's generate a signature for a request to update a media file. We will make a PATCH request to https://api.3playmedia.com/v3/files/100 with parameters name, api_key, signature, and signature_expires. Let's use the following mock values:

• name=foo
• api_key=123abc
• signature_expires=1445471340

Our signature payload will be /v3/files/100|PATCH|api_key=123abc&name=foo&signature_expires=1445471340 (remember, paramters must be alphabetized). This gives us a Base-64 encoded SHA-256 hash value of iLwRQXzXq69A7Uxq965bYZi/StZDGr7+SFU3aj4l8pM= (no line feed).

When used in curl (where we have to remember to URI-escape characters such as / and =), this might look like:

curl -X PATCH "https://api.3playmedia.com/v3/files/100?api_key=123abc&name=foo&signature_expires=1445471340&signature=iLwRQXzXq69A7Uxq965bYZi%2FStZDGr7%2BSFU3aj4l8pM%3D"