Zenegy uses OAuth 2.0 for user authorization and API authentication. Applications must be authorized and authenticated before they can fetch and post data from and to Zenegy or get access to data.

Zenegy provides two environments production and test. Environments have separate data and authentication. Authentication server urls are:

Parameter Description Sandbox
Production No
Test Yes

Configure Your Application

Before starting with the OAuth flow you need to register create your app. Please check following link

Authorization Code Flow

If you need to gain refresh token for long access to the company Authorization code flow is recommended. Authorization code flow returns short lived accesstoken and refresh token which can be used for acquiring accesstoken for unlimited period. This flow involves several steps.

Request an Authorization Code

Required parameters for this flow are:

Parameter Description Required
response_type The value of this field should always be: code Yes
client_id Unique id of the application, generated by Zenegy Yes
redirect_url The URI your users are sent back to after authorization. This value must match one of the OAuth 2.0 Authorized Redirect URLs. Redirect url has to be https Yes
company_id Guid of the company for which access is required, if user has access to the company this company will be pre selected Yes


Once redirected, the user is presented with Zenegy authentication screen. On this screen application name,logo,access scopes and required roles are presented to the user. Users need to select a company for which access will be granted. Users can validate access(grant access) or Deny access.

auth screen example

Your Application is Approved

By providing valid Zenegy credentials and clicking Validate Access, the user approves your application's request to access the interact with Zenegy on their behalf. This approval instructs Zenegy to redirect the member to the callback URL that you defined in your redirect_uri parameter.

Attached to the redirect_uri is the OAuth 2.0 authorization code. Parameter code is returned as query param.



The code is a value that you exchange with Zenegy for an OAuth 2.0 access token in the next step of the authentication process. For security reasons, the authorization code has a 5 -minute lifespan and must be used immediately. If it expires, you must repeat all of the previous steps to request another authorization code.

Exchange Authorization Code for an Access Token

The next step is to get an access token for your application using the authorization code from the previous step. To do this, make the following HTTP POST request with a Content-Type header of x-www-form-urlencoded:


    POST /auth/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded

Parameter Description
access_token The access token for the application. Token life is 1 hour.
expires_in The number of seconds remaining until the token expires. Currently,all access tokens are issued with a 1 hour lifespan.
token_type Always Bearer
refresh_token Refresh token, that is used in the refresh token flow for getting new access tokens
company_id Guid of the company for which access is granted


    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "OWViZWNhYWE4NDkzNDNkZDhjYjQ3M2Q1NzI0MmM5OTM=",
    "company_id": "ba8d4080-5828-42d1-a702-96615b527c67"

Make Authenticated Requests

Once you've obtained an access token, you can start making authenticated API requests on behalf of the user by including an Authorization header in the HTTP call to Zenegy API.

    GET /api/companies/{company_id} HTTP/1.1
    Authorization: Bearer {access_token}

Handling Invalid Tokens

If you make an API call using an invalid token, you'll receive a 401 Unauthorized response from the server, and you'll have to regenerate the token. A token could be invalid due to the following reasons:

  • It has expired.
  • The member revoked the permission they initially granted to your application.

A predictable expiry time is not the only contributing factor to an invalid token so it's very important that you code your applications to properly handle a 401 Unauthorized error by redirecting the member back to the start of the authorization workflow.

Your Application is Rejected

If the member chooses to cancel, or the request fails for any reason, the client is redirected to your redirect_uri callback URL with no code attached.

Refresh Tokens

Parameter Description
grant_type The value of this field should always be refresh_token.
refresh_token The number of seconds remaining until the token expires. Currently, all access tokens are issued with a 1 hour lifespan.
client_id Unique id of the application, generated by Zenegy when you registered your application.
client_secret The Client Secret value generated by Zenegy when you registered your application.


    POST /auth/token HTTP/1.1
    Content-Type: application/x-www-form-urlencoded


        "token_type": "bearer",
        "expires_in": 3599,
        "refresh_token": "OWViZWNhYWE4NDkzNDNkZDhjYjQ3M2Q1NzI0MmM5OTM=",
        "company_id": "ba8d4080-5828-42d1-a702-96615b527c67"