Excerpt |
---|
This page describes the authorization process of third-party Apps with VoipNow. |
Table of Contents | ||
---|---|---|
|
Overview
Voipnow APIs uses use the OAuth 2.0 protocol for the authentication and authorization of your App. That identification Identification takes the form of an OAuth 2.0 access token.
...
Access token validity & expiration
When you obtain an access Access token obtained from VoipNow , it is valid immediately become valid as soon as they are received and can be used in API requests. The access Access tokens are only valid for a period of 2 hours. After that 2 hours, the access token is considered expired and the App must request another token or refresh it.
...
The App redirects the user to the server authorization endpoint. The App must make a HTTP POST or GET request to the authorization endpoint located at https://<hostname>/oauth/authorize.php. The request URI is made by adding the following parameters to the query component (when using GET) or to the body of the request (when using POST) and it uses the The App must make a request to the endpoint in order to get the token, either using GET or POST. When making the request, the header Content-Type must be set to application/x-www-form-urlencoded formatand the body must contain the Request Parameters listed in the table below:
Name | Required | Description |
response_type | Yes | Always set to code. |
redirect_uri | Yes | URI where the system sends the response. Must be URL encoded if it's sent in the query parameters. |
client_id | Yes | App Key as generated by the system at registration time. |
state | No, but 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 following example below demonstrates shows how to make a POST request to the authorization endpoint:
...
Note |
---|
We strongly advise you to send the state parameter in the request and validate or /invalidate the response received from the system, if the state does not correspond to the one initially sent. |
Step 2
In order to obtain authorization, an App needs the permission of the userAn App cannot obtain the authorization without the user's permission. Once the App makes the request, the user receives the following form appears to the user:
Step 3
User The user permits or denies forbids the App to access its their 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 an the account of a third-party application (e.g Google).
To deny the authorization of the App, the user must click the Deny button. Anchor app-code-4 app-code-4
Step 4
The App receives an authorization code. If the user has been granted access to the App, the system will redirect him/her them to the URI specified in the redirect_uri parameter. The system uses the HTTP GET method to make the request to the App's endpoint:
...
The authorization code received has a lifetime of 10 minutes.
Step 5
The App must request an access token. Using the authorization code received in the previous step, the App must make a HTTP POST request to the token endpoint located at https://<hostname>/oauth/token.php. The request URI is made by adding using the following parameters to in the body of the request and it uses the application/x-www-form-urlencoded format. In the The Request Parameters are listed in table below you can find the Request Parameters:
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 |
Can be missing if sent in the Authorization header. |
The following example shows The example below demonstrates how to make a POST request to the token endpoint:
Code Block | ||
---|---|---|
| ||
POST /oauth/token.php
Host: <VoipNowHostname>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=632848d4033835dba1232cb5983ac971e51a214925bcbcad2f601a2a2c62009&redirect_uri=https://<hostname>/app/redirecturi/&client_id=5~2wKMPg9h~GExN3s01-7wX2XmLI_Xbz&state=appstate&client_secret=Q-jxXg90OX_mCpXvLfw.V12X3NQv-nc5&state=appstate |
Anchor app-code-6 app-code-6
Note |
---|
Client authentication is performed as described in the OAuth standard: https://tools.ietf.org/html/rfc6749#section-2.3. This means that client_id, client_secret can be sent in the Authorization header or in the body of the request. |
Step 6
The App receives the access token. Assuming that the code is still valid and the operation is successful, the App receives the following response.
Code Block | ||
---|---|---|
| ||
HTTP 1.1 200 OK
...
{
"access_token":"1|5~2wKMPg9h~GExN3s01-7wX2XmLI_Xbz|1|1345716093|O_XQYdHR0P-xMvqbVsh_OwRH7GT4.FtR",
"expires_in":7200,
"token_type":"Bearer",
"refresh_token":"9_s2TBCQ1y.PPzVNXkT-Gff6tB9z_bqr",
"state":"appstate"
} |
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.
- device_id: The id of the device associated with the token
When 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.
...
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 using the following parameters to in the body of the request and it uses the application/x-www-form-urlencoded format. In The Request Parameters are listed 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.Can be missing if it's sent in the Authorization header. |
Note |
---|
Client authentication is performed as described in the OAuth standard: https://tools.ietf.org/html/rfc6749#section-2.3. This means that client_id, client_secret can be sent in the Authorization header or in the body of the request. |
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 | ||||
---|---|---|---|---|
|
...
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 using the following parameters to in 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. Can be missing if it's sent in the Authorization header. | |||
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.
Note |
---|
Client authentication is performed as described in the OAuth standard: https://tools.ietf.org/html/rfc6749#section-2.3. This means that the client_id and client_secret can be sent in the Authorization header or in the body of the request. |
Step 2
The App receives the access_token. The response is similar to the response one 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.
...
At any time, the user can remove the authorization granted to the App by following the steps described recommendations in the Apps Management section.
Use an access token
You can use access_tokens when you make When making requests using one of the APIs. For , you can make use of access_tokens. 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.