Authorization Code Grant Type

The authorization code grant type is best for web applications, and native applications which can use or embed a browser or other user agent. In this authentication/authorization flow, the end user is redirected to the Axosoft website, where they can log in and authorize the client application with access to Axosoft data. The client application is then provided with an Authorization Code, which it can use to obtain an Access Token.

Direct the User Agent to the Axosoft authorization URL

To initiate this authorization flow, redirect the end user's browser to the URL <BaseOnTimeURL>/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.

For example, you might redirect the user's browser to the following URL:

https://someaccount.ontimenow.com/auth?response_type=code
                                      &client_id=00000000-0000-0000-0000-000000000000
                                      &redirect_uri=https://myontimeapp.com/receive_authorization_code
                                      &scope=read%20write

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.

Receive the Authorization Code or error

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://myontimeapp.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://myontimeapp.com/receive_authorization_code?error=access_denied
                                                  &error_description=User%20refused%20access

Exchange the Authorization Code for an Access Token

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 <BaseOnTimeURL>/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 OnTime. 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"
}

Access Axosoft Data

Once you obtain a valid Access Token, you can access Axosoft data.