DW Cloud OAuth API Spec
-----------------------------------
Related Digital Watchdog VMS Apps: DW Spectrum IPVMS
Last Edit: November 21, 2024
-----------------------------------
API Spec
This article will describe the different scopes and endpoints available in the API.
Related Articles
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 DW Spectrum 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.
|
Scope |
Cloud |
Server |
Explanation |
|
https://dwspectrum.digital-watchdog.com/ cloudSystemId=* |
Can make any cloud request. |
Can generate access tokens for interacting with a specific DW Spectrum Server. |
The token has the broadest scope possible. |
|
https://dwspectrum.digital-watchdog.com/cdb/oauth2/token cloudSystemId=* |
Can only be used to generate, inspect, and revoke tokens. |
Can generate access tokens for interacting with a specific DW Spectrum Server. |
The token can only make requests related to tokens |
|
https://dwspectrum.digital-watchdog.com/cdb/system cloudSystemId=* |
Can only be used to interact with DW Spectrum System API calls. |
Cannot be used with DW Spectrum Server. |
The token can only make api calls related to DW Spectrum Systems. |
|
cloudSystemId={some system id} |
Does not work with DW Spectrum Cloud. |
Can be used to make api calls to the DW Spectrum Server. |
The token only works with the cloud system id specified in the scope. |
OAuth Endpoints
The requests below that have payloads use the application/json content type.
Access Token Request
A token request URL where the web app exchanges an authorization grant to get an access token and an optional refresh token from the DW Cloud. Log in to DW 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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.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://dwspectrum.digital-watchdog.com/oauth/revoke/' \
--header 'Authorization: Bearer {access token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "{refresh or access token}"
}'
Getting Info from Tokens
The token introspection extension defines a protocol that returns information about an access token. Add the access token to the header.
curl --location --request GET 'https://dwspectrum.digital-watchdog.com/oauth/introspect/?token={access token}' \
--header 'Authorization: Bearer {access token}'
For More Information or Technical Support
DW Technical Support: 866.446.3595 (option 4)
https://www.digital-watchdog.com/contact-tech-support/
______________________________________________________________________________
DW Sales: 866.446.3595 [email protected] www.digital-watchdog.com
