Page tree

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

This page describes the authorization process of third-party Apps with VoipNow.

Overview

Voipnow APIs uses the OAuth 2.0 protocol for authentication and authorization of your App. That identification takes the form of an OAuth 2.0 access token.

The App is required to use TLS when making any of the requests described below.

Access token validity & expiration

When you obtain an access token from VoipNow, it is valid immediately and can be used in API requests. The access tokens are only valid for a period of 2 hours. After that the access token is considered expired and the App must request another token or refresh it.

Obtain authorization

Access tokens are obtained using one of the flows described below:

Request user permission

Step 1

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 application/x-www-form-urlencoded format:

NameRequiredDescription
response_typeYesAlways set to code.
redirect_uriYesURI where the system sends the response.
client_idYesApp Key as generated by the system at registration time .
stateNo, but recommendedParameter 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 example below demonstrates how to make a POST request to the authorization endpoint:

HTTP Request
POST /oauth/authorize.php
Host: <VoipNowHostname>
Content-Type: application/x-www-form-urlencoded
 
response_type=code&redirect_uri=https://<hostname>/app/redirecturi/&client_id=5~2wKMPg9h~GExN3s01-7wX2XmLI_Xbz&state=appstate
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 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 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.

Step 4

App receives an authorization code.  If the user has been granted access to the App, the system will redirect him/her 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:

GET /app/redirect/endpoint/?code=632848d4033835dba1232cb5983ac971e51a214925bcbcad2f601a2a2c62009f&state=appstate
Host: <AppHostname>
Content-Type: application/x-www-form-urlencoded

The authorization code received has a lifetime of 10 minutes.

Step 5

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 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:

NameRequiredDescription
grant_typeYesAlways set to authorization_code
codeYesThe code received in STEP 4.
redirect_uriYesURI where the system returns the response.
client_idYesApp Key as generated by the system at registration time .
client_secretYesApp Secret as generated by the system at registration time .
stateNo, recommendedParameter 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 example below demonstrates how to make a POST request to the token endpoint:

HTTP Request
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

Step 6

App receives the access token. Assuming that the code is still valid and the operation is successful, the App receives the following response.

HTTP Response
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:

NameDescription
access_tokenValue of the access token. This value is used when making requests to APIs.
expires_inPeriod of time, in seconds, during which the token is valid.
token_typeThe type of the token. Only Bearer is possible.
refresh_tokenRefresh token that can be used to regenerate the token once expired.
stateState 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.

Use trusted apps

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:

NameRequiredDescription
grant_typeYesAlways set to client_credentials
redirect_uriYesURI where the system returns the response.
client_idYesApp Key as generated by the system at registration time  .
client_secretYesApp Secret as generated by the system at registration time .
stateNo, recommendedParameter 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.

Access token management

Refresh the access token

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.

NameRequiredDescription
grant_typeYesAlways set to refresh_token.
redirect_uriYesURI where the system returns the response.
client_idYesApp Key as generated by the system at registration time.
client_secretYesApp Secret as generated by the system at registration time.
refresh_tokenYesThe refresh token received in STEP 6 (The Request User Permission Section).
stateNo, recommendedParameter 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.

App De-authorization

At any time, the user can remove the authorization granted to the App by following the steps described in the Apps Management section.

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.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.