This article explains how to authenticate with the Media Server REST API using bearer tokens and provides a Python example to help you get started.

Overview

A bearer token is a temporary access credential that the system generates after you authenticate. Instead of sending your password with every request, you pass this token in your request headers. Tokens expire automatically or you can revoke them when your session finishes, which makes them more secure than transmitting passwords repeatedly.

Determine your user account type

How you log in depends on your account type:

• Local users: (such as admin in the Desktop Client): Authenticate directly with the Media Server API.

• LDAP users: (retrieved from your directory): Authenticate directly with the Media Server API. From the API perspective, LDAP users log in the same way as local users, though the username format might differ based on your directory setup.

• Cloud users: Authenticate through Cloud OAuth 2.0 rather than direct Media Server calls.

Authenticate local or LDAP users

To authenticate a local or LDAP user, make a single API request to retrieve a bearer token.

1. Define your connection variables

Set your Server address (including https:// and the port, typically 7001) and your account credentials.

import requests

server = 'https://192.168.1.10:7001'
username = 'admin'  # Or your LDAP username
password = 'your-password'

# The Media Servers use self-signed certificates by default.
# Disabling verification is acceptable for testing, but enable it in production.
session = requests.Session()
session.verify = False

2. Request a bearer token

Send a POST request to the /rest/v4/login/sessions endpoint. This is the only request that transmits your password. Set setCookie to False to prevent the server from issuing a browser cookie.

response = session.post(
    f'{server}/rest/v4/login/sessions',
    json={'username': username, 'password': password, 'setCookie': False},
)
response.raise_for_status()
login = response.json()

token = login['token']
print(f"Token acquired. Expires in {login['expiresInS']} seconds.")

The Media Server returns a JSON response containing your session details:

{
  "id": "{a1b2c3d4-...}",
  "username": "admin",
  "token": "vms-4f1c9e2a-...",
  "ageS": 0,
  "expiresInS": 600
}

The token field holds your bearer token, and expiresInS indicates its remaining validity period in seconds. When a token expires, you must authenticate again.

3. Use the bearer token in requests

Add the token to the HTTP Authorization header using the format Bearer <token>. Do not pass tokens in the URL.

auth_header = {'Authorization': f'Bearer {token}'}

# Example: Get details about the current session
response = session.get(
    f'{server}/rest/v4/login/sessions/current', 
    headers=auth_header
)

Handle HTTP response codes

When making authenticated requests, watch for these HTTP status codes:

• 401 Unauthorized: The token is invalid, expired, or revoked. To fix this, request a new token.

• 403 Forbidden: The token is valid, but the account lacks permission for the requested resource. To fix this, update your account permissions.

• 422 Unprocessable Content: Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it typically requires a fresh token. 

4. Delete the session

Delete the session when your task completes. Revoking the token immediately prevents unauthorized access during the remainder of its TTL (time-to-live).

session.delete(
    f'{server}/rest/v4/login/sessions/{token}', 
    headers=auth_header
)

Additional resources

• Refer to the Media Server REST API reference documentation for detailed endpoint specs.

• Download complete code samples from the Nx Open GitHub repository.