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 [email protected] and we will gladly create one for you.
One API client can be used for all MediaLab environments, e.g. both https://companyX.medialab.co and https://companyY.medialab.co. The API itself can be accessed by appending "/api" to the channel URL, e.g. https://company.medialab.co/api/.

When registering your app you will need to provide us with a valid redirect URI, to which the user will be redirected after an authorization call. We allow only one redirect URI per app, so you will receive different credentials for testing/staging/production environments.

Access token

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.
Example: if the user has not been given upload rights within MediaLab, the upload scope will not be available. The available scopes for a user can be checked at the /api/user/info endpoint.

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.

Scope	Description
basic	Basic read acces to files and folders
user.info	View user profile (includes name and email address)
manage	Edit / remove files and folders
upload	Upload files.
share	Share files either by mail or embed code.

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]"