This article describes the scopes and endpoints available in the API to get a proper HTTPS Bearer session token. Use the OAuth API over HTTPS or RTSPS only. Raw HTTP or RTSP requests are forbidden.

Important terms

• Access token: The credential used to access resources. It usually expires quickly, often within an hour.

• Refresh token: Used to get a new access token after the old one expires so the user does not need to log in again.

• Scope: Limits what the token can do. For example, it might only allow interaction with a specific site.

Grant types

To get proper access to a resource, your integration picks a grant type. The Cloud supports:

• password: Exchanges the user's Nx Cloud account credentials directly for a token.

• authorization_code: Exchanges an authorization code for a token. It is better suited to web apps with a backend server since it uses a redirect and does not expose credentials to the frontend.

• refresh_token: Exchanges a valid refresh token for a new access token to renew an expired one.

How scope works

In general, the scope specifies which APIs and resources an access token is authorized to work with. Tokens follow these rules:

• The scope cannot be expanded once restricted. To interact with another site, you need a new token. Generate a broad-scoped token and store it somewhere safe.

• Tokens only work with the Media Server when the scope includes cloudSystemId={some site id}.

• If a token does not have access to /cdb/oauth2/token, it cannot be used to revoke itself.

Scopes

• https://nxvms.com/cloudSystemId=*

  • Cloud: Can make any cloud request.

  • Server: Can generate access tokens for interacting with a specific Nx Witness Media Server.

  • Explanation: The token has the broadest scope possible.

• https://nxvms.com/cdb/oauth2/token/cloudSystemId=*

  • Cloud: Can only be used to generate, inspect, and revoke tokens.

  • Server: Can generate access tokens for interacting with a specific Nx Witness server.

  • Explanation: The token can only make requests related to tokens.

• https://nxvms.com/cdb/systems/cloudSystemId=*

  • Cloud: Can only be used to interact with Nx Witness site API calls.

  • Server: Cannot be used with Nx Witness server.

  • Explanation: The token can only make API calls related to Nx Witness sites.

• cloudSystemId={some site id}

  • Cloud: Does not work with Nx Witness Cloud.

  • Server: Can be used to make API calls to the Nx Witness Media Server.

  • Explanation: The token only works with the cloudSystemId specified in the scope.

OAuth endpoints

Because a Cloud user's account lives in Nx Cloud and not on the VMS server, your integration exchanges the user's Cloud credentials for a token through the Cloud DB's OAuth 2.0 endpoint (POST /cdb/oauth2/token). See the Cloud DB API Document - OAUTH2 for more details.

Requests with payloads below use the application/json content type.

Access token request

This endpoint exchanges an authorization grant for an access token and a refresh token from the Cloud. Log in to the Cloud and get your access and refresh tokens by making the POST request below. In the payload, fill in the code parameter with an access code unique to your integration (see also Authorizing a Web App for more details).

curl --location --request POST 'https://nxvms.com/oauth2/token/' \
--header 'Content-Type: application/json' \
--data-raw '{
"grant_type": "authorization_code",
"response_type": "token",
"code": "{some access code}"
}'

Add the parameter "scope": "{scope}" to the payload to give the generated tokens a scope different from the default scope of [https://nxvms.com](https://nxvms.com) cloudSystemId=*. Any of the scopes described above are valid.

Example response from the POST request:

{
"access_token": "{access token}",
"refresh_token": "{refresh token}",
"expires_in": "86400",
"expires_at": "1647743897438",
"token_type": "bearer",
"prolongation_period": "600",
"scope": "https://nxvms.com cloudSystemId=*"
}

The response contains an access_token and refresh_token generated with the default scope, along with the expiration time and token type.

To obtain resources from the Cloud site, make an API request with the access_token in the Authorization header:

curl --location --request GET 'https://nxvms.com/cdb/systems/' \
--header 'Authorization: Bearer {access token}'

Refresh token request

The refresh token enables authorization servers to extend an access token's lifespan. This allows for shorter, more secure token lifespans without requiring the user to re-authenticate when the token expires.

Add the refresh_token obtained from the Access token request section to the refresh_token grant parameter in the POST request:

curl --location --request POST 'https://nxvms.com/oauth/token/' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "cloud_portal",
"grant_type": "refresh_token",
"response_type": "token",
"refresh_token": "{refresh token}",
"scope": "https://nxvms.com cloudSystemId=*"
}'

Get an access code with a refresh token request

Integrations use the refresh_token grant type to exchange a refresh token for a new access token when the access token has expired. This allows web apps to maintain a valid access token without requiring further input from the user.

Add the refresh_token from prior sections to the refresh_token grant parameter in the POST request below to generate an access code:

curl --location --request POST 'https://nxvms.com/oauth/token/' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "cloud_portal",
"grant_type": "refresh_token",
"response_type": "code",
"refresh_token": "{refresh token}",
"scope": "https://nxvms.com cloudSystemId=*"
}'

Revoking token request

Use this endpoint to revoke OAuth tokens issued to an integration. When revoking tokens, revoke the refresh token first. Pass the token to revoke as a query parameter and include the active access_token in the Authorization header.

curl --location --request DELETE 'https://nxvms.com/cdb/oauth2/token?token={refresh or access token}' \
--header 'Authorization: Bearer {access token}'

Getting info from tokens

The token introspection extension defines a protocol that returns information about an access token. Place the token in the request body to see the attributes associated with the token.

curl --location --request POST 'https://nxvms.com/oauth2/introspect' \
--header 'Authorization: Bearer {access token}' \
--data-raw '{
"token": "{refresh or access token or any token}"
}'

Sample

See Authorizing a Web Application for an example showing real usage of the requests above.