Skip to main content

​
Overview

This guide outlines the steps necessary for integrating the OAuth authentication workflow between an Actor (end user), a Host (client application), and Quicko.

Actor

The end user who initiates the OAuth flow

Host

Your client application requesting access to Open APIs

OAuth App

Quicko’s OAuth application that manages authentication

​
OAuth Flow

OAuth Authentication Flow The OAuth flow involves four main steps:

​
Workflow Steps

1

Initialization from Host

The Host sends an intent along with options to the OAuth App.Options include:
  • API Key (provided during onboarding)
  • Redirect URI (where the user returns after consent)
The Host application initiates the flow by redirecting the Actor to Quicko’s OAuth application.
2

Actor Consent on OAuth

The OAuth App authenticates and obtains consent from the Actor.Authentication Process:
  1. OAuth App sends an OTP to the Actor to establish their identity
  2. Actor enters the OTP to verify their identity
  3. Actor is presented with a consent screen
  4. Actor reviews and approves the Host’s access request
The Actor must be a registered Quicko user to complete this step.
Once consent is given, the OAuth App generates a request_token for the Host.
3

Redirection Back to Host

Upon the Actor’s consent, the OAuth App redirects back to the Host.Redirect Details:
  • Issues HTTP 302 status code
  • Redirects to the URI provided by the Host
  • Appends the Resource Owner’s request_token as a query parameter
https://your-app.com/callback?request_token=eyJhbGciOiJIUzUxMi...
4

Acquiring Access and Refresh Tokens

The Host exchanges the request_token for long-lived tokens.The Host calls the OAuth Authorize API with:
  • request_token (from the redirect)
  • x-api-key (your API key)
  • API User’s access_token (from authenticate endpoint)
Response includes:
  • Resource Owner’s access_token - to access Open APIs
  • Resource Owner’s refresh_token - to get new access tokens
Securely store both tokens in your database associated with the Actor’s account.

​
Understanding Different Tokens

All of the tokens mentioned below belong to the Actor (Resource Owner), not your application.
There are various types of tokens that serve different purposes within the OAuth 2.0 framework. This section explains the different tokens involved in the interaction between your app and Quicko.
Description: A short-lived token which the Host must exchange to receive the Resource Owner’s access token.
PropertyValue
Lifetime10 minutes
PurposeInitiate token exchange
SourceReturned after Actor grants consent
UsageExchange for access token via OAuth Authorize API
The request token expires after 10 minutes. Exchange it immediately for access and refresh tokens.
Description: Used by the Host to access Quicko’s Open APIs on behalf of the Resource Owner.
PropertyValue
Lifetime24 hours
PurposeAccess Open APIs
SourceReceived via OAuth Authorize API
UsageInclude in Authorization header when calling Open APIs
Example:
curl https://api.quicko.com/income-tax/tax-payer \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMi..." \
  -H "x-api-key: your_api_key"
When the access token expires, use the refresh token to obtain a new one without requiring the Actor to re-authenticate.
Description: Long-lived token for obtaining new access tokens without user interaction.
PropertyValue
Lifetime1 year
PurposeObtain new access tokens
SourceReceived via OAuth Authorize API
UsageExchange for new access token via Authorize API
When to use:
  • Access token has expired (after 24 hours)
  • You receive 401 Unauthorized response from Open APIs
  • Proactively refresh before expiry
Securely store the refresh token and implement automatic token refresh logic in your application to ensure uninterrupted API access.

​
Complete OAuth Journey

The diagram above illustrates the complete OAuth flow:
  1. Redirect - Host App redirects user to Quicko OAuth with api_key and redirect
  2. Redirect - After user consent, Quicko redirects back to Host App with request_token
  3. Authorize - Host App calls Quicko API Server with request_token
  4. Response - Quicko API Server returns access_token and refresh_token
  5. End - Host App can now access Open APIs on behalf of the user

​
Best Practices

Secure Storage

Store tokens securely in your database with encryption. Never expose them in client-side code or logs.

Token Refresh

Implement automatic token refresh logic before the access token expires to ensure seamless API access.

Error Handling

Handle token expiration gracefully. Catch 401 errors and automatically refresh the access token.

User Consent

Respect user consent. Provide clear options for users to revoke access to their data.

​
Next Steps

OAuth Authorize API

Learn how to exchange request tokens for access tokens

Open APIs

Explore the available Open APIs you can access