- 17 Jan 2024
- Print
Authentication
- Updated on 17 Jan 2024
- Print
Authenticate to movingimage API with OAuth 2.0
The movingimage REST API uses OpenID Connect 1.0 and OAuth 2.0 for authentication. Authentication is a multi-step process:
Discover the authorization endpoint. The authorization endpoint is the URL where you will exchange your credentials for an access token. You can discover the authorization endpoint by calling the
/.well-known/openid-configuration
endpoint.Obtain an access token. Use the authorization endpoint to obtain an access token. You will need to provide your credentials (a VideoManager Pro login or an authorization code) in order to do this.
Include the access token in your API requests. When you make an API request, you must include the access token in the authorization header. The authorization header must be formatted as follows:
Authorization: Bearer <access_token>
Refresh the access token when it expires. Access tokens expire after a short period of time. When this happens, you will need to refresh the access token. You can do this by calling the
/oauth/token
endpoint.
Here is an example of an API request that uses the Get VideoManagers
method and includes an access token:
GET https://api.movingimage.com/v1/videomanagers
Authorization: Bearer <access_token>
Authenticate to movingimage API with OpenID Connect
To begin using the API, you first need to know how to authenticate yourself.
If you are using VideoManager Pro under a custom domain, the endpoints for authenticating a user are discoverable.
Step 1: Discover the OpenID Connect Provider location
The OpenID Connect Provider location is the URL where you can request the authentication endpoints. For the vast majority of customers, the location is https://api.video-cdn.net/.well-known/webfinger
.
You can use the following curl command to make a request to this endpoint:
curl https://api.video-cdn.net/.well-known/webfinger?resource=https://api.video-cdn.net/v1/
The response will be a JSON object containing the following information:
The issuer location: This is the URL of the OpenID Connect Provider.
The keycloak realm: This is the name of the keycloak realm that you need to use to authenticate.
The auth server URL: This is the URL of the authorization server.
{
"subject": "https://api.video-cdn.net/v1/",
"properties": {
"https://api.video-cdn.net/v1/keycloak/realm": "platform",
"https://api.video-cdn.net/v1/keycloak/auth-server-url": "https://login.movingimage.com/auth/"
},
"links": [
{
"rel": "http://openid.net/specs/connect/1.0/issuer",
"href": "https://login.movingimage.com/auth/realms/platform/.well-known/openid-configuration"
}
]
}
Step 2: Discover the authentication endpoints
The issuer location that you received in the previous step contains a link to the OpenID Provider configuration data. You can use the following curl command to make a request to this endpoint:
curl https://login.movingimage.com/auth/realms/platform/.well-known/openid-configuration
The response will be a JSON object containing the following information:
The authorization endpoint: This is the URL where you will exchange your credentials for an access token.
The token endpoint: This is the URL where you will get a new access token when your current token expires.
{
"authorization_endpoint": "https://login.movingimage.com/auth/realms/platform/protocol/openid-connect/auth",
"token_endpoint": "https://login.movingimage.com/auth/realms/platform/protocol/openid-connect/token"
}
Use the authorization endpoint to obtain an access token
Once you have discovered the authentication endpoints, you can use the authorization endpoint to obtain an access token. You will need to provide your credentials (username and password) in order to do this.
Include the access token in your API requests
When you make an API request, you must include the access token in the authorization header. The authorization header must be formatted as follows:
Authorization: Bearer <access_token>
Refresh the access token when it expires
Access tokens expire after a short period of time. When this happens, you will need to refresh the access token. You can do this by making a request to the token endpoint.
Access and refresh tokens
Access tokens and refresh tokens are unique identifiers used to authenticate users and grant access to protected data.
Access Tokens
Provide authorization for accessing API-provided data
Have a limited lifespan, necessitating refresh tokens for extended access
Refresh Tokens
Generate new access tokens when existing ones expire
Maintain seamless access without requiring repeated authentication
Token Acquisition
Access and refresh tokens are issued following successful user authentication. These tokens are obtained using endpoints discovered in the previous chapter.
Integration Scenarios
The choice of token acquisition method depends on the integration type. Refer to the table below for the appropriate scenario:
Scenario | Description | Token Acquisition Method |
---|---|---|
Anonymous Users | Applications accessing a single VideoManager Pro account belonging to the developer. Users don't need VideoManager Pro accounts. | Implicit Grant |
Logged-in Users (Client-side) | Browser-based applications that redirect users to VideoManager Pro for authentication. Users grant access, and the browser receives a code exchanged for an access token. | Authorization Code Grant |
Logged-in Users (Server-side) | Server-side applications that redirect users to VideoManager Pro for authentication. Users grant access, and the server receives a code exchanged for an access token. | Authorization Code Grant |
Authorization Grant Flow
The authorization grant flow is the corresponding OAuth mechanism used to retrieve access tokens.