The V1 authentication and OAuth APIs are deprecated and are being phased out. The following documentation is only for existing partners who are already using it. If you are a new partner please refer to OAuth V2
The safe retrieval of secure resources while protecting user credentials can be achieved by OAuth 2.0.
The OAuth 2.0 specification defines a delegation protocol that is useful for conveying authorization decisions across a network of web-enabled applications and APIs. OAuth is used in a wide variety of applications, including providing mechanisms for user authentication. This has led many developers and API providers to incorrectly conclude that OAuth is itself an authentication protocol and to mistakenly use it as such.
Once you have registered as a Deskera developer and received your
client_secret, they can be used to implement the standard Oauth 2.0 three legged flow to allow user to authorize the application to access Deskera APIs.
The OAuth connection flow
A user connects to your platform using the following OAuth connection flow:
- Starting on a page at your site, the user clicks a link that takes them to Deskera App Authentication page, passing along your app's
- On Deskera's app auth page, the user provides the necessary information for connecting to your platform.
- A call is made to the
callback_urigiven during app registeration along with an authorization code (this code can be used to get access_token and refresh_token for accessing the user's Deskera data).
- On successfull response of the call back API, the Deskera app auth page will redirect the user to a
redirect_uriof your choice.
Step 1: The OAuth Link
The Deskera endpoint should receive these parameters:
response_type, with the value code
scope, with the value write
client_id, with app's client ID generated during registration
state(optional), state value
redirect_uri(optional), The redirect URI that the user should be taken to after authorization. This must be sent encoded
Sample OAuth Link
Step 2: Users connect their Deskera account
Once on the Deskera App auth page, the user would be prompted to input his/her Deskera user name and password and asked to authorize the app. The user should be already registered to Deskera Books and have atleast one orhganisation before coming to this step.
Step 3: Callback request with Auth Code
After the user connects their existing account to your platform, we'll make an API call to the
callback_uri with the below parameters
statevalue, if any
code, authorization code that is to be used get the tokens as described in next steps. This auth code is short lived and for one time use only.
Sample callback request
Step 4: Platform completes the Deskera account connection and gets tokens
Provide the code received in the Step 3 to the API below to get the tokens from Deskera. The
deskera-token can be used to make API calls to Deskera Books and the
deskera-refresh-token can be used to fetch a new
deskera-token in case it expires.
Authorization header consists of Basic + baseEncode64(clientId:clientSecret)
Sample request to get tokens
curl --location --request POST 'https://bifrost.deskera.com/oauth/token?grant_type=authorization_code&scope=read+write&code=0P2xhb' \
--header 'Authorization: Basic Y2xfcHViX2I5N2Q3MDI0ZmI4ZjQ5OGU4YmE0YjIwOTljMmRhMjAyOmNsX3ByaXZfNmZ'
Sample response for get tokens API
"username": "My Org",
"org": "Singapore Org"
deskera-token is not a permanent token and might become invalid time to time. At any point of time the validity of the token can be checked by calling the below API.
Sample request to check if token is valid
curl --location --request GET 'https://bifrost.deskera.com/v1/iam/token/app/validate' \
--header 'x-access-token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYW1Vc2VySWQiOjEyNzQ3LCJ3ZWJzaXRlIjoiU2luZ2Fwb3JlIE9yZyIsImlzT3J'
200 response for the above API would mean that the token is still valid.
In case the token is invalid, the deskera token can be refreshed by using the below API
Sample request to refresh token
curl --location --request POST 'https://bifrost.deskera.com/v1/iam/auth/app/getrefreshtoken' \
--header 'Content-Type: application/json' \
"refreshToken" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYW1Vc2VySWQiOjEyNzQ3LCJ3ZWJzaXRlIjoiU2luZ2Fwb3JlIE9yZyIsImlzT3JnU2V0Ijp0cnVlLCJ1c2V"
Sample respone for refresh token
In the above refresh token API response -
Step 4: User is redirected to Application
callback_uri return a 2XX response and is successfully able to fetch the tokens and complete the connection, the user UI is then redirected to the
redirect_uri, if any provided in step #1.
deskera-token contains many privileges, keep it secure!
Your platform can now use these token to access various Deskera APIs.