OAuth 2

Authentication is done using the OAuth 2 workflow. A lot of resources are available with regards to OAuth 2 by doing a quick search on the internet. Below is described how this applies to the MediaLab API.

The MediaLab API supports the authorization code and refresh token grants. A typical authentication flow looks like this:

1. The app requests authorization to access resources from the user by redirecting the user to the /api/oauth2/authorize endpoint.
2. If the user authorizes the request, the user will be redirected back to the app along with an authorization code.
3. The app can then request an access token at the /api/oauth2/token endpoint using the authorization code and its own client identification.
4. The API will provide an access token (lifespan of 1 hour) and a refresh token (lifespan of 60 days) which the app can use to authenticate to the API.
5. The app will need to provide a valid access token for every request made, either using an authorization header or parameter.
6. When the access token has expired, the app can request a new one directly at the /api/oauth2/token endpoint using the refresh token.
7. If also the refresh token has expired, the app must redirect the user to the /api/oauth2/authorize endpoint to request a new access token.

App registration

In order to use the API you will need to register an API client with us. It is currently not possible to do this online, please send us an email at support@medialab.co and we will gladly create one for you.

A valid access token is required for all requests to the API, except for the /api/oauth2 endpoints, and can be retrieved as described under 'Authentication'. This access token can be provided in several ways according to the OAuth2 specification:

1. For GET requests, the access token can be provided under the 'access_token' GET parameter.
2. For POST requests, the access token can be provided under the 'access_token' POST parameter.
3. For all requests, the access token can be provided using an 'Authorization' header, which has the format 'Authorization: Bearer access_token_goes_here'

Scopes

When requesting an authorization code you need to provide the scopes for the session. Please do note that only scopes the user has access to will be available.

To request multiple scopes on the initial authorization attempt, provide a space separated list of scopes to the /api/oauth2/authorize endpoint. If you require a scope that you did not originally request when retrieving the access token, you must forward the user with the new scopes to the /api/oauth2/authorize endpoint so that the user can grant you access.

Private token

If you are not developing an application to be used by other users, but only need access to your personal account, we allow authentication using a private token. This can also be used to access your account from a command-line application as it does not require a manual action once it has been set up. Please note this method should only be used for your personal account, and your private token should never be shared with someone else. It provides full access to your account.

The private token can be generated when you are logged in, by browsing to 'Settings', then under 'Profile' choose 'API access'. Currently we allow 1 private token per account. You can generate / revoke the token and use it directly with our API.

Once you have generated your private token, there are 2 ways to pass your token:

1. Passing the token in an Authorization header (recommended):
   
   

   curl https://demo.medialab.co/user/info -H Authorization: Private-Token [TOKEN_GOES_HERE]

2. Passing the token as either GET or POST parameter named 'private_token':
   
   

   curl -X POST https://demo.medialab.co/upload/file -F private_token=[TOKEN_GOES_HERE]