API Spec

This article will describe the different scopes and endpoints available in the API.

How scope works

In general, the scope specifies which APIs and resources an access token is authorized to work with.

Tokens have the following rules:

• The scope cannot be expanded once restricted. You will need a new token if you want to interact with another system. To make things simple you should generate a broad scoped token and keep them somewhere safe.
• Tokens with only work with the Nx Witness Server when the scope is cloudSystemId={some systemid}
• If a token does not have access to /cdb/oauth/token it cannot be used to revoke itself.

OAuth endpoints

The requests below that have payloads use the application/json content type.

Access Token Request

A token request URL where theweb app exchanges an authorization grant to get an access token and an optional refresh token from the Nx Cloud. Log in to Nx Cloud and get your access and refresh tokens by performing the POST API request below. In the payload, fill in the code parameter with an access code unique to your integration (go to step 4 of  "Authorizing a Web App" to see how we achieve this).

curl --location --request POST 'https://nxvms.com/oauth/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 above payload if you would like the tokens generated by the POST request to have a scope different than the default scope of https://nxvms.com cloudSystemId=*. You can use any of the scopes described in the How scope works chart above.

Example response from the above 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. Their expiration time and token type are provided.

To perform a POST request with the access_token to obtain resources from the Cloud System, perform an API request with the access_token in the authorization header. See an example request below.

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

Refresh Token Request

The refresh token exists to enable authorization servers to refresh the access tokens lifespan, allowing for shorter, more secure lifespans for access tokens without involving the user when the token expires.

Add the refresh_token obtained from the Getting tokens 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 have a valid access token without further involvement from the user.

Add the refresh_token from the 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

A URL where you can revoke OAuth tokens issued to an integration. When revoking tokens make sure that you revoke the refresh token first. Add the access token to the header and refresh token or access token to the token parameter.

curl --location --request POST 'https://nxvms.com/oauth/revoke/' \
--header 'Authorization: Bearer {access token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "{refresh or access token}"
}'

curl --location --request GET 'https://nxvms.com/oauth/introspect/?token={access token}' \
--header 'Authorization: Bearer {access token}'