Authentication

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:

1. 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.

2. 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.

3. 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>

4. 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:

The authorization grant flow is the corresponding OAuth mechanism used to retrieve access tokens.