The zencontrol cloud APIs use OAuth 2.0 protocol for authentication and authorization. This allows all OAuth 2.0 supported client applications to securely access resources within the zencontrol cloud.
Generating client credentials
To begin, OAuth 2.0 client credentials need to be generated (contact support). The information required to generate client credentials are:
- Username/email
- Client application name
- Redirect url (eg. https://www.my-client-domain.com/oauth/callback)
If successful, the credentials generated will include:
- Client ID
- Client secret
These credentials should be used by your OAuth 2.0 client application to authorize requests against the zencontrol cloud APIs.
Gaining authorization to user resources
GET https://login.zencontrol.com/oauth/authorize
Before a client application can access the zencontrol cloud APIs, it must request access to a user's resources. Firstly, a GET request is sent to https://login.zencontrol.com/oauth/authorize with the following query parameters:
| Parameter | Description |
| client_id | The client ID from the generated credentials. |
| state | An opaque value used by the client to maintain state between request and callback. |
| response_type | Must be set to "code". |
| redirect_uri | The redirect url provided with credentials. |
Following is an example request for client ID "abcd" with redirect url "http://client/callback":
https://login.zencontrol.com/oauth/authorize?client_id=abcd&state=request1&response_type=code&redirect_uri=http%3A%2F%2Fclient%2Fcallback
If the user grants access to their resources, the server will redirect to the redirect url with following query parameters:
| Parameter | Description |
| code | The authorization code used for generating access token. |
| state | The opaque value provided in authorize request. |
Following is an example redirect for the above example authorization request:
http://client/callback?code=newauthorizationcode&state=request1
Generating access tokens
POST https://login.zencontrol.com/oauth/token
After gaining authorization to a user's resources, the provided authorization code can be used to generate access tokens. Access tokens are used for authenticating requests against the zencontrol cloud APIs. A POST request is sent to https://login.zencontrol.com/oauth/token with the following data:
| Parameter | Description |
| client_id | The client ID from the generated credentials. |
| client_secret | The client secret from the generated credentials. |
| redirect_uri | The redirect url provided with credentials. |
| grant_type | Must be set to "authorization_code". |
| code | The authorization code returned from successful authorization. |
If successful, the server will return a JSON object containing the following:
| Parameter | Description |
| token_type | Always set to "Bearer". |
| expires_in | UTC timestamp of when the token will expire. |
| access_token | The access token used for authenticating API requests. |
| refresh_token | The refresh token for refreshing access tokens. |
Refreshing access tokens
POST https://login.zencontrol.com/oauth/token
Access tokens can be refreshed before expiring using the refresh token returned when generating the access token. Refreshing an access token will generate a new access and refresh token for authenticating requests against the zencontrol cloud APIs. The previous access and refresh tokens will be revoked and as such need to be replaced with the refreshed access and refresh tokens. To refresh an access token a POST request is sent to https://login.zencontrol.com/oauth/token with the following data:
| Parameter | Description |
| client_id | The client ID from the generated credentials. |
| client_secret | The client secret from the generated credentials. |
| grant_type | Must be set to "refresh_token". |
| refresh_token | The refresh token returned from generating an access token. |
If successful, the server will return a JSON object containing the following:
| Parameter | Description |
| token_type | Always set to "Bearer". |
| expires_in | UTC timestamp of when the token will expire. |
| access_token | The access token used for authenticating API requests. |
| refresh_token | The refresh token for refreshing access tokens. |
Sending API requests
GET https://api.zencontrol.com/v1/
When sending REST requests against the zencontrol cloud API, requests must include the access token in one of the following:
| Field | Parameter | Description |
| HTTP Header | Authorization |
The access token prepended with "Bearer " |
| Cookie | access_token | The access token. |
| Content | accessToken | The access token. |
Comments
0 comments
Article is closed for comments.