Authentication

Authentication Guide

This guide covers the authentication methods available for integrating with the E-Invoicing API. There are two main authentication methods, each with different requirements and use cases.

1. Direct Integration Authentication Method

Overview

Direct Authentication uses the OAuth 2.0 Client Credentials flow, which is suitable for server-to-server communication where your application acts on its own behalf. Use Case: When your application directly manages your own invoices. Authentication Method: OAuth 2.0 Client Credentials Flow

Authentication Flow

Register Application: Get client credentials from the developer portal
Request Access Token: Use client credentials to obtain an access token
Make API Calls: Include the access token in API requests
Refresh Token: Renew the access token before expiration

Step 1: Get Access Token

Sample Request

curl -X POST ${AUTH_BASE_URL}/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Sample Response

Step 2: Use Access Token

Sample API Call

2. On Behalf Integration (Delegated) Authentication Method

Overview

On Behalf Authentication uses a combination of Client Credentials (for Resource APIs) and Authorization Code flow (for Invoice APIs). This allows your application to act on behalf of multiple businesses with their explicit consent. Use Case: When your application manages invoices on behalf of multiple tax payers. Authentication Method:

OAuth 2.0 Client Credentials Flow (for Resource APIs)
OAuth 2.0 Authorization Code Flow (for Invoice APIs)

Authentication Flow

Invoice APIs: Use Authorization Code flow with user consent
User Authorization: Redirect users to authorization endpoint
Exchange Code: Exchange authorization code for access token
Make API Calls: Use appropriate token for each API type

Step 1: Redirect User for Authorization (Invoice APIs)

Sample Authorization URL

const authUrl = new URL('${AUTH_BASE_URL}/oauth2/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('redirect_uri', 'https://your-app.com/callback');
authUrl.searchParams.set('scope', 'invoices');
authUrl.searchParams.set('state', 'random-state-string');

// Redirect user to this URL
window.location.href = authUrl.toString();

Step 2: Handle Authorization Callback

Sample Callback Handler

// In your callback endpoint (e.g., /callback)
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // Verify state parameter to prevent CSRF attacks
  if (state !== 'expected-state-value') {
    return res.status(400).send('Invalid state parameter');
  }

  // Exchange authorization code for access token
  const tokenResponse = await fetch('${AUTH_BASE_URL}/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      code: code,
      redirect_uri: 'https://your-app.com/callback'
    })
  });

  const tokenData = await tokenResponse.json();
  const invoiceAccessToken = tokenData.access_token;
  const refreshToken = tokenData.refresh_token;

  // Store tokens securely (e.g., in database with user association)
  // Redirect user back to your application
  res.redirect('/dashboard');
});

Step 3: Use Token to call API

Sample API Calls

// Use Authorization Code token for Invoice APIs
const invoiceResponse = await fetch('${API_BASE_URL}/invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${invoiceAccessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(invoiceData)
});

Token Management

Access Token Expiration

Both authentication methods use access tokens that expire after a certain period (typically 1 hour). Implement proper token refresh logic:

Token Refresh Example

async refreshInvoiceAccessToken() {
  const response = await fetch('${AUTH_BASE_URL}/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: this.clientId,
      client_secret: this.clientSecret,
      refresh_token: this.refreshToken
    })
  });

  const tokenData = await response.json();
  this.invoiceAccessToken = tokenData.access_token;
  this.refreshToken = tokenData.refresh_token;
  
  return this.invoiceAccessToken;
}

Next Steps

Now that you understand the authentication methods, explore these related topics:

Resource - Access reference data
Invoice Management - Create and manage invoices
Invoice Inbox - Manage received invoices

Overview

Getting Started

Support

Authentication Guide

1. Direct Integration Authentication Method

Overview

Authentication Flow

Step 1: Get Access Token

Step 2: Use Access Token

2. On Behalf Integration (Delegated) Authentication Method

Overview

Authentication Flow

Step 1: Redirect User for Authorization (Invoice APIs)

Step 2: Handle Authorization Callback

Step 3: Use Token to call API

Token Management

Access Token Expiration

Next Steps

Overview

Getting Started

Support

​Authentication Guide

​1. Direct Integration Authentication Method

​Overview

​Authentication Flow

​Step 1: Get Access Token

​Step 2: Use Access Token

​2. On Behalf Integration (Delegated) Authentication Method

​Overview

​Authentication Flow

​Step 1: Redirect User for Authorization (Invoice APIs)

​Step 2: Handle Authorization Callback

​Step 3: Use Token to call API

​Token Management

​Access Token Expiration

​Next Steps

Authentication Guide

1. Direct Integration Authentication Method

Overview

Authentication Flow

Step 1: Get Access Token

Step 2: Use Access Token

2. On Behalf Integration (Delegated) Authentication Method

Overview

Authentication Flow

Step 1: Redirect User for Authorization (Invoice APIs)

Step 2: Handle Authorization Callback

Step 3: Use Token to call API

Token Management

Access Token Expiration

Next Steps