The authorization code grant type is best for web applications, and native applications which can use or embed a browser or other user agent and is required for creating Public Applications. In this authentication/authorization flow, the end user is redirected to the Axosoft website, where they log in and authorize the client application with access to Axosoft data. The client application is then provided an Authorization Code, which is then used to obtain an Access Token.
To initiate this authorization flow, redirect the end user's browser to the URL <BaseAxosoftURL>/auth, with the following parameters in the url query:
| Parameter | Description |
|---|---|
| response_type | The type of response you are expecting. To receive an Authorization Code, it must have the value code. Required. |
| client_id | The Client ID issued to you through Axosoft. Required. |
| redirect_uri | The URL to which the end user will be redirected once they allow or disallow access to your app. This should be a URL handled by your app, and will receive either an Authorization Code (which can then be exchanged for an Access Token) or an error. Required. |
| scope | A space-separated list of scopes your app is requesting. Valid scopes are read (which allows your app to read existing Axosoft data), and write (which allows it to add and update Axosoft data). If you need both, supply read write. If omitted, defaults to read. |
| state | If supplied, this value will be passed on to the Redirect URL after the end user allows or disallows access to your app. |
| expiring | Sets expiration date of token. Use false to request a non-expiring token. If omitted, defaults to 30 days. |
For example, you might redirect the user's browser to the following URL:
https://someaccount.axosoft.com/auth?response_type=code
&client_id=00000000-0000-0000-0000-000000000000
&redirect_uri=https://myaxosoftapp.com/receive_authorization_code
&scope=read%20write
&expiring=false
When the user is redirected to the Axosoft authorization page, he or she will log in to the Axosoft Suite if needed, and be asked to allow your app access to Axosoft data.
If the user approves access, their user agent will be redirected to the supplied Redirect URL, and the request will include the following parameters in the URL query:
| Parameter | Description |
|---|---|
| code | The Authorization Code which can be exchanged for an Access Token. |
| state | If the state parameter was passed with a value to the Authorization Code request, that same value will be provided here. |
For example, the user might be redirected to the following URL after allowing access to your app:
https://myaxosoftapp.com/receive_authorization_code?code=12345678-1234-1234-1234-123456789012
If the end user denies your app access, or if an error occurred with the request, the end user will also be redirected to the Redirect URL, and the request will include the following parameters in the URL query:
| Parameter | Description |
|---|---|
| error | An error code. |
| error_description | A more detailed description of the error intended for the developer of your app. |
| state | If the state parameter was passed with a value to the Authorization Code request, that same value will be provided here. |
For example, the user might be redirected to the following URL after denying access to your app:
https://myaxosoftapp.com/receive_authorization_code?error=access_denied
&error_description=User%20refused%20access
If the end user granted your app access and you receive an Authorization Code, you can exchange the Authorization Code for an Access Token by making a GET request to the URL <BaseAxosoftURL>/api/oauth2/token. The request should include the following parameters in the URL query:
| Parameter | Description |
|---|---|
| grant_type | The type of grant you are providing. For the authorization grant type, it must have the value authorization_code. Required. |
| code | The Authorization Code previously provided to the Redirect URL. Required. |
| redirect_uri | The same Redirect URL that was provided earlier in the Authorization Code request. Required. |
| client_id | The Client ID issued to you through Axosoft. Required. |
| client_secret | The Client Secret issued to you through Axosoft. Required. |
If the request is successful, the response will include the following:
| Parameter | Description |
|---|---|
| BODY DATA | A JSON object with the following properties: access_token: (string) The Access Token which can be used to access protected resources via the API. token_type: (string) The type of the Access Token. You are receiving a bearer token, so this will contain the value "bearer".data: (object) An object containing a few properties of the user associated with the Access Token, such as id, first_name, last_name, and email.
|
For example, you might receive the following data in the response body after a successful request:
{
"access_token" : "10101010-1010-1010-1010-101010101010",
"token_type" : "bearer",
"data" : {
"id" : 7,
"first_name" : "Cathy",
"last_name" : "O'Reilly (Dev)",
"email" : "Cathy.Oreilly@mycompany.com"
}
}
If the request fails, the response will have a status of 400 Bad Request and will have contents as follows:
| Parameter | Description |
|---|---|
| BODY DATA | A JSON object with the following properties: error: (string) An error code. error_description: (string) A more detailed description of the error intended for the developer of your app. |
For example, you might receive the following data in the response body after a failed request:
{
"error" : "invalid_request",
"error_description" : "One or more parameters are missing: client_secret"
}