Usage and lifetime of Tokens

  • Give the exchange token to the API URL to receive an access token and a refresh token. The lifetime of the exchange token depends on the granted access that you received. 
  • The Access token will expire in a specified time. Unless you are a trusted application, the lifetime of the access token will be one day.
  • The refresh token won't expire. Please keep it secret and secure. You need to provide the refresh token to get a new access token when your access token is expired.
  • An Access token is required each time you send a request to access the resource.

You must keep the exchange token and the refresh token secret and secure. They are the keys to access all resources.

Access Token and Refresh Token from Exchange Token

Every request to the API needs to provide an access token.

There are 2 ways to manage the access token:

  1. Follow the workflow of OAuth 20 we describe below
  2. Use our support library (.NET & C#) with the example of code after

1. OAuth 2.0 flow for getting access token

In order to get the access token, we make a POST request with below parameters:


    •  {Rest Api Host}/OAuth20/Token 


    • Authorization Basic {Email encoding in base64string}

    • Accept Application/json

Content Form:

    • grant_type  exchange_token

    • code {exchange token client received}

After the request is verified, Rest API will send a response to client. Status code (200) Success will have the content in json string like below:


access_token: "gAAAAAA5-ybbpTLnRm6Resegac4n1er3Kydv4plMN_UStrP6_r8lt1k6DMS7v5imwMgBf4cHUEqg46vz0Hgv1zOhgUAa3Av4Xi4NeFeKag2U8jkCaOwqA7GL-vNyd755pA9G4mTI5d49T_HThz8tLFG3YpI-OGzyZMYNelVmD4opfIFSJAEAAIAAAAAi33OFlXo_ovjGJEw018Mck5e9QDcvjpAU6FDh18vMJn_3zzB2-H8OOY3kRHW1YUijbs7jHhkN1Ov_ZvjZnn7_vgo8z91_Ye2Kg-b1sOJ1ccntBnBVAI97R6py85jhL28F5GrrJH4qhC0IVj36NAeCxIwvtaNT-ZgSLWKe3xTQYDJTwI3UYNL3_qdBHT3aRUbwBjWTaX1lfQCfQ5-6EY38X3oLgkAo0S_N_4Wrn8zL185vHS7yed6qWtGcoTC58OKR22q0sncpfr82U5PGNZCR4y2bPPAxKMeTBR8Nq39wtw6YvRq2X_gwbys42hchzF8KsNH2wRk6z5E16kc2i-CudxsFHM3OkmZHaEfc-0bRUmMY4zkSF_2_QJTD53et_Bs"
scope: null
token_type: "bearer"
expires_in: "900"
refresh_token: "TGe0!IAAAAE8fYMG6jWY0rbV5Kwz4ApGmYenMyg-cEGCxBiKEH0NJwQAAAAHAat8cqFEyBOcA9X50LY5eXtDqSgShk9NYxpfQWYapnAJzZ6n8RtlAf34sbHCO3vFJnny6y96MsPJcttCudXY9_IIn3zappOYRfePAQmOJUuOvgCj50RKo6CsxjJ5ymo49HsCWXy7aQqL1wXbEDjlF-gZmCZuQcgw8cjlFMR0NtvzOAVim49-S5fB88fH1TSx9L4s_mZs0qWq9JHcPYiUnbswaz__gfHYb-3Nl0SlWJA-2-KEgww-b_k8jmVEWAQk"

2. Using Winbooks.Apis.Services for getting access token

To make it easier, we provide a library called  Winbooks.Apis.Services to handle all workflows.


All management of the access token, refresh token and exchange token is handled by the library. You just need to provide 3 parameters:

  • Rest API host
  • Email
  • Exchange token
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Winbooks.Apis.Services;
namespace Winbooks.Apis.Demo
    public class Program
        static void Main(string[] args)
            UserCredential userCredential = new UserCredential(""
            if (userCredential.Authentication())
                string refreshToken = userCredential.RefreshToken;
                string accessToken = userCredential.AccessToken;


See the document on the Winbooks.Apis.Services for some examples of usage.

  • No labels