Authentication


Getting Started

Before getting started, with Authentication, it is good to know first what kind of integration that you are building. OnlinePajak OpenAPI provides by default two different types of integration:

  1. Private Application or a Host-to-Host Integration

    A Private Application integration is intended for integrators, who want to access and create resource on behalf of themselves.

    For example, you are a Company that wants to import your data to OnlinePajak seamlessly from your ERP software. Then the Private Application integration is the best that matches your need, as the Authentication flow is much simpler and more straight-forward.

  2. Public Application or an OAuth Platform Integration

    A Public Application integration is intended for integrators, who want to access and create resource on behalf of their users.

    For example, you are a Company that provides an online SaaS platform. You want to provide an integration where your user can import their data on your platform to OnlinePajak seamlessly. Then, the Public Application integration is the appropriate integration that you need to use, as you need an Authorization first from your user before you can have access to protected resource.

The OnlinePajak OpenAPI uses Access Token (or API Key) to authenticate requests regardless of the type of integration. Authentication to the API is performed via the Bearer Token Authentication, which means all requests will need to include an Authorization header (-H "Authorization: Bearer 4eC39HqLyjWDarjtT1").

Make sure to keep your Access Token safe. Do not share your Access Token in a public accessible areas. Depending on the type of integration you want to build, the method to retrieve the Access Token will differ.

Private Application

The Authentication of Private Application is really simple and straight-forward to setup, the only task that you need to do is to create an Access Token for a Company that your OnlinePajak user has access to, by following these steps:

  1. Login to your Developer Account.
  2. Click on the + Create button and selct App from the drop down and move to the Private Apps tab.
  3. Select the Company that you want to create an Access Token to.

Note: You still need to wait for the activation of your application before you can retrieve your Access Token.

Then, on each request provide the Access Token as a Bearer token in the Authorization header and you can start accessing protected resource, e.g.:

Sandbox URL:

POST /v1.0/invoices HTTP/1.1
Host: openapi.demo-achilles.systems
Authorization: Bearer {your.token.here}
Accept: application/json
Content-Type: application/json

Production URL:

POST /v1.0/invoices HTTP/1.1
Host: openapi.online-pajak.com
Authorization: Bearer {your.token.here}
Accept: application/json
Content-Type: application/json

Public Application

The Public Application integration uses the OAuth 2.0 protocol to authenticate your client application and grant accesses to the user's protected resources. If you are unfamiliar with the protocol, you can read more about it here. In general, the protocol flow looks something similar to this:

OAuth 2.0 Generic Flow

  1. The Application (Client) asks for authorization from the Resource Owner in order to access the resources.
  2. Provided that the Resource Owner authorizes this access, the Application receives an Authorization Grant. This is a credential representing the Resource Owner's authorization.
  3. The Application requests an Access Token by authenticating with the Authorization Server and giving the Authorization Grant.
  4. Provided that the Application is successfully authenticated and the Authorization Grant is valid, the Authorization Server issues an Access Token and sends it to the Application.
  5. The Application requests access to the protected resource by the Resource Server, and authenticates by presenting the Access Token.
  6. Provided that the Access Token is valid, the Resource Server serves the Application's request.

Source: Auth0.com

There are actually four main flows to retrieve an Access Token as defined by the OAuth 2.0 Authorization Framework specification, these are called Grant Types. But for our integrators, we will only use the Authorization Grant type.

1. Retrieve Your OAuth 2.0 Client Credential

To begin, you need to retrieve your OAuth 2.0 client credentials first from OnlinePajak OpenAPI Dashboard. If you had followed the step-by-step provided in the Getting Started guide, then you should already have it.

Once you have your Client ID, we can start with the User Authorization. To allow your application to access the user's protected resource, the user will need to grant you a permission first. We will achieve this by redirecting your user to OnlinePajak OpenAPI Authorization page and your client_id and response_type needs to be provided in the query parameters.

Optionally, you can also include a state parameter that provides a functionality similar to a CSRF token, to ensures that the callback that will be invoked, really originated from your application. And you can also provide a reference_id parameter that can map to your internal session identifier, to help with identifying your user more easily.

Sandbox URL:

GET https://oauth.demo-achilles.systems/authorize
        ?client_id={xxxx}
        &response_type=code
        [&state={xxxx}]
        [&reference_id={xxxx}]

Production URL:

GET https://oauth.online-pajak.com/authorize
        ?client_id=xxxxxx
        &response_type=code
        [&state={xxxx}]
        [&reference_id={xxxx}]

At this step, the user will need to enter their OnlinePajak credentials or register a new one, if they don't have any. If the user had successfully authenticated or if there are any errors, we will always redirect the user back to your registered callback URL.

For example, had you registered the following callback URL: http://integration.com/onlinepajak/callback upon adding your client application in the dashboard. Then upon successful authorization, we will call the callback URL as following:

GET http://integration.com/onlinepajak/callback
        ?code={xxxx}
        [&state={xxxx}]
        [&reference_id={xxxx}]

Or had some failures occured during the authorization process, then the callback URL will be:

GET http://integration.com/onlinepajak/callback
        ?error={error message}
        [&state={xxxx}]
        [&reference_id={xxxx}]

3. Exchange the Authorization Code with an Access Token

Before your application can acccess the OpenAPI endpoint, you need to exchange the Authorization Code with an Access Token. To do this you need to call the Access Token endpoint with your Client ID, Client Secret and Authorization Code. Note that this request should be called from your backend, as your Client Secret should not be exposed to public.

Sandbox URL:

POST https://oauth.demo-achilles.systems/access_token

Production URL:

POST https://oauth.online-pajak.com/access_token

The payload should look something like this:

{
  "client_id": "{your Client ID here..}",
  "client_secret": "{your Client Secret here...}",
  "grant_type": "authorization_code",
  "code": "{the code from callback...}"
}

And the response should have the following structure:

{
  "token_type": "bearer",
  "access_token": "JzDdWQs7grCfRlt9zXIJ0P5neCUaXejE",
  "company": {
          "name": "Company Name",
          "npwp": "12.345.678.9-012.345" 
        },
  "user": {
          "email": "sample-email@online-pajak.com"
        }
}

4. Create Request

After you have stored the access_token value, then on each request to the protected resource include the access_token as the Bearer Token in the Authorization header.

Sandbox URL:

POST /api/v1.0/invoices HTTP/1.1
Host: openapi.demo-achilles.systems
Authorization: Bearer {your.token.here}
Accept: application/json
Content-Type: application/json

Production URL:

POST /api/v1.0/invoices HTTP/1.1
Host: openapi.online-pajak.com
Authorization: Bearer {your.token.here}
Accept: application/json
Content-Type: application/json