How to

The following section contains information and "how-to" guides on how to use the Movio Exhibitor API. This includes how to obtain a token, how to use the token to authenticate requests.

When you want to use the Movio Exhibitor API, you will need to obtain a token from the token issuer. This token is used to authenticate requests to the Movio Exhibitor API. The token is obtained by using the OAuth2 client_credentials flow. There are a lot of resources on the internet that can help you understand OAuth2 and the client_credentials flow in more detail. We've provided a simple guide below on how to obtain a token.

1. Obtain your client_id and client_secret from Movio EQ under Settings.

2. Base64 encode your client_id:client_secret and add it to the Authorization header prefixed with Basic.

   # This will output the base64 encoded string of the client_id and
   # client_secret. For this example, the client_id is `random_client_id`
   # and the client_secret is `very_secret_client_secret`.
   echo 'random_client_id:very_secret_client_secret' | base64
   cmFuZG9tX2NsaWVudF9pZDp2ZXJ5X3NlY3JldF9jbGllbnRfc2VjcmV0Cg==
   

   In this case, a valid authorization header would be: Authorization: Basic cmFuZG9tX2NsaWVudF9pZDp2ZXJ5X3NlY3JldF9jbGllbnRfc2VjcmV0Cg==.

3. Send a POST request to the token issuer with the following parameters:

   • audience: The URL of the API.
   • scope: The scopes that the token has.
   • grant_type: This must be client_credentials.

   Thise parameters should be form-URL-encoded in the body of the request. Make sure any request to the token issuer is done over HTTPS, as the request will contain sensitive information not meant to be shared in plain text.

   POST /oauth/token HTTP/1.1
   Host: https://<token_issuer_url>
   Content-type: application/x-www-form-urlencoded
   Accept: application/x-www-form-urlencoded, application/json
   Authorization: Basic cmFuZG9tX2NsaWVudF9pZDp2ZXJ5X3NlY3JldF9jbGllbnRfc2VjcmV0Cg==
   
   audience=API_IDENTIFIER&scope=SCOPES&grant_type=client_credentials
   

4. The token issuer will then return a token in the response body. The token will be in the following format:

   {
     "access_token": "abcd1234.abcd1234.abcd1234",
     "scope": "read:foo write:bar",
     "expires_in": 1234,
     "token_type": "Bearer"
   }
   

5. The access_token is the token that is used to authenticate requests to the Movio Exhibitor API.

Note that the token will usually be valid for 24 hours. This means that you will need to obtain a new token every 24 hours.

🔗 More information about the client_credentials flow can be found here:

• Client Credentials Flow (Auth0)
• OAuth2 RFC 6749, section 4.4

With the token_type and access_token obtained from the token issuer, you can now authenticate your requests to the Movio Exhibitor API.

1. Create a new request to the Movio Exhibitor API.

2. Add an Authorization header to the request with the token as the value. The header should be in the following format:

   POST /v1/contact-lists/1234/contacts HTTP/1.1
   Host: <movio_api_url>
   Content-Type: application/json
   Authorization: <token_type> <access_token>
   

Parameter	Description
access_token	The access token. This token is used to authenticate requests to the Movio Exhibitor API.
audience	The audience. This is the url of the API.
client_id	The client ID. This is the ID of the application that is requesting the token.
client_secret	The client secret. This is the secret of the application that is requesting the token.
expires_in	The expiry time of the token in seconds.
grant_type	The grant type. This must be client_credentials.
scope	scope is a space-separated list of scopes that the token has.
token_type	The token type. This will always be of type Bearer.