OAuth2 Protocol for the REST API

All clients follow a basic message flow to access the Cherwell REST API using OAuth2. To begin, a user must obtain a client ID from CSM Administrator. Client IDs contribute to the security of the REST API by providing unique keys that work in conjunction with a User's CSM privileges.

After obtaining the client ID, the User performs a full login to the REST API using the client ID and their CSM User credentials. A successful login generates an access token, which allows the User agent to access the REST API as long as the token remains valid.

Note: The security settings that are configured for your Users will remain in effect when they access the REST API.

An Access token is needed for all subsequent calls to the REST API to identify the User agent as a valid API user. The life span of the Access token is based on the client ID's settings. Access tokens tend to have a relatively short life span and can be refreshed with a Refresh token.

Refresh tokens are used to periodically refresh the Access token without the need to provide credentials again. Refresh tokens tend to have a longer life span than Access tokens and are also based on the client ID's settings. Once the Refresh token has expired or the user is logged out, a full login must be performed to obtain new tokens. It is not always necessary to use Refresh tokens, which are generally considered safer over non-encrypted transport protocols, such as HTTP. If you use an HTTPS connection, you can increase the Access token life span and use Access tokens for all subsequent connections.

Note: To further secure your system, use SSL.

Users who log in to the REST API client consume a CSM license.