Developer Guide

Authorization Code Flow in Tenzo for Partners

If you are a developer and you'd like to integrate with Tenzo in a way that allows each of your individual customers to authenticate separately - this is the place to start.

Getting Started

For now - you'll need to ask us directly to create an application – you can email partnerships@gotenzo.com to start this process.

One thing we will need from you is a list of redirect URLs – this is the location in your own application that a user will be redirected to after granting permission to their Tenzo data within Tenzo.

You should also let us know what data you're looking to pull e.g., forecast data, sales data, or both.

After making this request, we'll send you the following data:

Client ID
Client Secret
List of scopes that we've granted you (these can be used later)

Now you're ready to start writing code!

How do I go and get a customer specific access token?

The Authorization Code grant type is used by API applications integrating with Tenzo's API to exchange an authorization code for an access token. Allow the user to trigger the authorisation flow from your system by implementing the following flow:

Your system sends the user to Tenzo's authentication server
The user is directed to the Tenzo authorization / consent screen and approves the app's request
The user is redirected back to your system with an authorization code in the query string
Your system exchanges the authorization code for a refresh token and an access token
Your system automatically handles the continuous refresh token exchange

Requirements and Limitations

The Tenzo OpenApi requires HTTPS
Tenzo OAuth access tokens expire after 10 hours. After expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted
Refresh tokens do not expire. However, if you lose a refresh token or the user revokes the access, you must repeat the full OAuth authorization code flow to obtain a new OAuth access token and a refresh token.

Flow for Authorization Code Exchange

Authorization request to auth.gotenzo.com
Consent page
Authorization code capture
Code exchange
Refresh Token / Access Token
Revoke token / Disconnect

1Authorization request to auth.gotenzo.com

Your application should redirect the user to the following address:

https://auth.gotenzo.com/o/authorize?client_id={clientId}&response_type=code&redirect_uri={redirectUri}&scope={scopes}&state={state}
            

Parameters:

client_id [Required] The value for APP ID you received when creating your application
redirect_uri [Required] The URL value for Redirection URL you set when you created your application. You can set up to 3 redirect urls for your application (use localhost for development purposes). Please remember to url encode this value.
response_type [Required] The value must be "code" indicating the code authorization grant type is required and an authorization code is desired in the response.
scope [Required] This should contain all the scopes you were emailed when creating your application
state [Optional] Use this parameter to pass a unique value that will be returned to you after user completes the authorization. Use this if you want to make your app more resilient to CSRF attacks.

Example:

curl --location --request GET 'https://auth.gotenzo.com/o/authorize?client_id=xxxxxxxx-xxxxxx&scope=tenzo/sales:read&redirect_uri=http://example.com/code&response_type=code&state=xyzABC123'
            

We recommend using one of our graphics for a button that will take your users to Tenzo.

2Consent page

Users of your application will then be redirected to Tenzo's login page. Here he or she will be able to enter their login details and will then be shown a consent screen where all of the requested scopes for your application will be listed.

After giving consent the user will be redirected to the URL specified in the authorization request

3Authorization code capture

Tenzo will redirect back to the url specified in the redirect_uri parameter. We will append to an HTTP query string with values for code and state (if provided in auth requests). E.g.,

{redirectURL}?code={code}&state={state}

code: One-time use authorization code that you should use in order to obtain an access and refresh token.
state: We will return the value you've provided with the authorization request, so that you can verify it and prevent CSRF attacks.

4Code exchange

You can now exchange the code for an OAuth access token. Your application will need to make the following POST request to Tenzo's token endpoint:

POST https://auth.gotenzo.com/o/token/
Content-Type: application/x-www-form-urlencoded
            

The body of the request should contain five parameters:

client_id - your application id
client_secret - your application client secret received when you created the app
grant_type - authorization_code
code - authorization code you've extracted in the 3rd step
redirect_uri - redirection url you've set up for your application

5Getting an Access Token and Refresh Token

Tenzo will verify all of the provided parameters with the request. If everything goes well you will receive a response with data in JSON format containing the access token.

{ "access_token": "...", "expires_in": 36000, "token_type": "Bearer", "scope": "tenzo/sales:read tenzo/forecast:read tenzo/area:read tenzo/location:read …", "refresh_token": "...", "uid": "..." }

The returned JSON object will contain other properties such as:

access_token: The access token value. Use this token to access Tenzo's API resources
expires_in: The remaining lifetime of the access token measured in seconds.
refresh_token: Token that should be used to acquire a new access token.
scope: Enumeration of scopes

You can now use the access token to access Tenzo's resources.

When calling the API you should set the header to include:

X-AUTH-TOKEN: <token received in step 5>

6Refreshing your token

To refresh a token, you want to make another call to the token endpoint with subtly different parameters:

POST https://auth.gotenzo.com/o/token/
Content-Type: application/x-www-form-urlencoded
            

The body of the request should contain five parameters:

client_id - your application id
client_secret - your application client secret received when you created the app
grant_type - refresh_token
refresh_token - the token received in steps (5) above
redirect_uri - redirection url you've set up for your application

This will return you a new access token.

7Revoke token / Disconnect from Tenzo

In some cases your users would like to disconnect from Tenzo. To revoke a token you need to send a POST request from your application to revoke endpoint.

POST https://auth.gotenzo.com/o/revoke_token/
Content-Type: application/x-www-form-urlencoded
            

client_id [Required]: The value for APP ID you received when creating your application
token [Required]: RefreshToken received in step 5

8How do I finally make an API call now I have a token?

Now, you can call our API using the "OAuth" style of authentication referenced here - for example

GET https://api.gotenzo.com/public/v1/general/locations/

HEADERS = {
    "Authorization": "Bearer <insert token from step5/6>"
}
            

Need Help?

Email support@gotenzo.com with any issues.