Skip to main content

OAuth2 Token Endpoint

Overview

The OAuth2 token endpoint is used to generate access tokens required for accessing protected resources. The available grant types include:

  • authorization_code
  • refresh_token
  • client_credentials
  • urn:ietf:params:oauth:grant-type:jwt-bearer

Base URLs:

  • DEV: https://api.dev.koffi.vn/api
  • UAT: https://api.uat.koffi.vn/api
  • Production: https://uat.koffi.vn/api

Endpoint:

  • URL: /v2/oauth/token
  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Headers:
    • Authorization:
      • Depends on grant type authorization will be needed
      • JWT bearer token required for urn:ietf:params:oauth:grant-type:jwt-bearer grant.
      • Basic authentication required for client_credentials grant.

Parameters:

  • grant_type (required): Defines the OAuth2 grant type to be used. Allowed values are:

    • authorization_code
    • refresh_token
    • client_credentials
    • urn:ietf:params:oauth:grant-type:jwt-bearer
  • assertion (required for JWT Bearer Grant): The assertion string when using the JWT bearer grant type.

  • scope (optional): The scopes requested for the token, space-separated. Read scopes for more detail

    • Example: ob.invoices.readonly ob.products.readonly
  • tenant_connection_code (optional for all, required for client_credentials grant): The tenant code for which the token is requested. Defaults to the client application’s tenant if not provided. Read


Grant Types and Usage

1. Client Credentials Grant

  • Used by clients to request a token using their client credentials.
  • Read Application for more detail how to get client_id, client_secret, tenant_connection_code.
  • Each tenant in Koffi has a unique connection code. The client application must provide the corresponding connection code when interacting with a specific tenant.
  • Refresh token is not returned in this grant type

Authorization Header:

The Authorization header for this grant type should contain a basic authentication token, which is a base64 encoded string of client_id:client_secret.

Request Example:

curl --location --request POST 'https://api.dev.koffi.vn/api/v2/oauth/token' --header 'Authorization: Basic <base64(client_id:client_secret)>' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=client_credentials' --data-urlencode 'scope=ob.invoices.readonly ob.products.readonly' --data-urlencode 'tenant_connection_code=<your_tenant_code>'

Response:

{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scopes": [
"ob.invoices.readonly",
"ob.products.readonly"
]
}

2. Authorization Code Grant

TBD

3. Refresh Token Grant

TBD

4. JWT Bearer Grant

  • Used by clients to request a token using their JWT Bearer Grant.
  • Read Application for more detail how to get client_id, private_key, public_key, Keypair_id.
  • Use private_key and public_key to generate JWT Bearer Grant.

Generate JWT Bearer Grant:

{
"alg": "RS256",
"typ": "JWT",
"kid": "<your Keypair_id>"
}
Payload
{
"sub": "<prefix_impersonate>:<impersonate>",
"iss": "<your client_id>",
"aud": "<environment>",
"iat": <inti_timestamp>,
"exp": <expire_timestamp>
}

NOTE:

  • prefix_impersonate: possible values: koffi.user.email or koffi.user.id
  • if prefix_impersonate is koffi.user.email then impersonate is email of the user you want to represent
  • if prefix_impersonate is koffi.user.id then impersonate is id of the user you want to represent
data = base64(Header) + "." + base64(Payload)
JWT Bearer Grant = data + "." + RSASHA256(data)

Request Example:

curl --location --request POST 'https://api.dev.koffi.vn/api/v2/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' --data-urlencode 'scope=ob.invoices.readonly ob.products.readonly' --data-urlencode 'assertion=<your JWT Bearer Grant>'

Response:

{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600,
"scopes": [
"ob.invoices.readonly",
"ob.products.readonly"
]
}

Common Authentication Error

Error response

In case of an error, the response will have an HTTP status code other than 200, with the following format

{
"code": "error_code",
"message": "error_message"
}

Error code

  • EOAU001: Invalid grant type
  • EOAU002: JWT Bearer Grant requires assertion
  • EOAU003: JWT Bearer Grant assertion invalid or expired
  • EOAU004: JWT Bearer Grant assertion client id (iss) is required (iss)
  • EOAU005: JWT Bearer Grant assertion key id (kid) is required
  • EOAU006: JWT Bearer Grant assertion key id (kid) is invalid
  • EOAU007: JWT Bearer Grant assertion audience (aud) is required
  • EOAU008: JWT Bearer Grant assertion user not found (sub)
  • EOAU009: Authorization header not found or invalid
  • EOAU010: Invalid tenant
  • EOAU011: Invalid tenant connection code or client application has no access to target tenant
  • EOAU012: Invalid scope <invalid-scopes>