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>