...
In order to obtain authorization, an App needs the permission of the user. Once the App makes the request, the following form appears to the user:
Step 3
User permits or denies the App to access its resources. To grant access to an App, the user must enter their credentials and click the Allow button. The user can also validate their credentials using a the an account of a third-party application (e.g Google). The Permission is option permits the user to generate an access token with the following properties:
- valid until revoked - this token is valid until the user removes it
- valid only once - this token is valid only once, other requests using it will fail
To deny the authorization of the App, the user must click the Deny button. Anchor app-code-4 app-code-4
...
| Name | Required | Description |
|---|---|---|
| grant_type | Yes | Always set to authorization_code |
| code | Yes | The code received in STEP 4. |
| redirect_uri | Yes | URI where the system returns the response. |
| client_id | Yes | App Key as generated by the system at registration time. |
| client_secret | Yes | App Secret as generated by the system at registration time. |
| state | No, recommended | Parameter to be used by the App to verify if the response received from the system is valid. From the point of view of the server, it does not matter how the state parameter is generated |
...
The response parameters are:
...
- access_token
...
- : Value of the access token. This value is used when making requests to APIs.
- expires_in
...
- : Period of time, in seconds, during which the token is valid.
- token_type
...
- : The type of the token. Only Bearer is possible.
- refresh_token
...
- : Refresh token that can be used to regenerate the token once expired.
- state
...
- : State parameters as received in the request.
No refresh_token is generated if the access token must be valid only once. When the token expires, the App can use the refresh token to generate another access_token or repeat the steps described above.
...
| Note |
|---|
| We advise you to use this flow only if you trust the App requesting authorization. Trusted Apps can be added as described in Register App documentation. |
Step 1
The App requests an access_token. It makes a HTTP POST request to the token endpoint located at https://<hostname>/oauth/token.php. The request URI is made by adding the following parameters to the body of the request and it uses the application/x-www-form-urlencoded format. In the table below you can find the Request Parameters:
| Name | Required | Description |
|---|---|---|
| grant_type | Yes | Always set to client_credentials |
| redirect_uri | Yes | URI where the system returns the response. |
| client_id | Yes | App Key as generated by the system at registration time. |
| client_secret | Yes | App Secret as generated by the system at registration time. |
| state | No, recommended | Parameter to be used by the App to verify if the response received from the system is valid. From the point of view of the server, it does not matter how the state parameter is generated. |
Step 2
App receives the access token. The response is similar to the response received in the previous flow. The only difference is that no refresh_token is generated. When the token expires, the App must request to authorize with the system again, by repeating the step above.
| Anchor | ||||
|---|---|---|---|---|
|
...
Once a token has expired, the App must generate a new one in order to access the system's resources. If the token was initially generated using the User Permission flow, you can refresh it using the refresh_token obtained. To do this you must follow the steps below:
Step 1
The App requests an access_token. It makes a HTTP POST request to the token endpoint located at https://<hostname>/oauth/token.php. The request URI is made by adding the following parameters to the body of the request and it uses the application/x-www-form-urlencoded format.
| Name | Required | Description |
|---|---|---|
| grant_type | Yes | Always set to refresh_token. |
| redirect_uri | Yes | URI where the system returns the response. |
| client_id | Yes | App Key as generated by the system at registration time. |
| client_secret | Yes | App Secret as generated by the system at registration time. |
| refresh_token | Yes | The refresh token received in STEP 6 (The Request User Permission Section). |
| state | No, recommended | Parameter to be used by Apps to verify that the response received from the system is valid. From the point of view of the server, it does not matter how the state parameter is generated. |
Step 2
App receives the access_token. The response is similar to the response received when using the User Permission flow. When this request is sent, the system invalidates the current refresh_token and returns a new one. The new refresh_token must be must be saved by the App.
...
Use an access token
You can use access_tokens when you make requests using one of the APIs. For more details, check out the authentication section of the UnifiedAPI or SystemAPI documentation.
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.