Authentication - Digitzs API Documentation

Overview

The Digitzs API uses a two-step authentication process to ensure secure access to your merchant services:

Authentication - Verifying your identity
Authorization - Granting access to API resources

All API requests require proper authentication headers. Tokens expire after one hour and must be refreshed.

Before You Begin

You will need the following credentials provided during onboarding:

API Key

Your unique API key (x-api-key)

Application ID

Your application identifier (appId)

Authentication Flow

Generate App Key

Create an app key using your API key and application ID

Create App Token

Use the app key to generate a temporary access token

Make Authenticated Requests

Include the token in your API requests

Step 1: Generate App Key

Create an app key that will be used to generate access tokens.

Creating a new app key renders the old key unusable. Store your app key securely.

Endpoint

POST /auth/key

Request Headers

Header	Value	Description
`x-api-key`	Your API key	Provided during onboarding
`Content-Type`	`application/json`	Standard REST header

Request Body

{
  "data": {
    "type": "auth",
    "attributes": {
      "appId": "your-application-id"
    }
  }
}

Request Parameters

Parameter	Type	Required	Description
`data`	object	Yes	Container for API data
`data.type`	string	Yes	Must be “auth”
`data.attributes`	object	Yes	Container for authentication attributes
`data.attributes.appId`	string	Yes	Your application ID from onboarding

Response

{
  "links": {
    "self": "https://api.digitzs.com/auth/key"
  },
  "data": {
    "type": "auth",
    "id": "your-api-key",
    "attributes": {
      "appKey": "generated-app-key"
    }
  }
}

Response Parameters

Parameter	Type	Description
`data.id`	string	Your API key (same as request header)
`data.attributes.appKey`	string	Generated app key for token creation

Code Examples

const axios = require('axios');

const createAppKey = async () => {
  try {
    const response = await axios.post(
      'https://api.digitzs.com/auth/key',
      {
        data: {
          type: 'auth',
          attributes: {
            appId: 'your-application-id'
          }
        }
      },
      {
        headers: {
          'x-api-key': 'your-api-key',
          'Content-Type': 'application/json'
        }
      }
    );

    const appKey = response.data.data.attributes.appKey;
    console.log('App Key:', appKey);
    return appKey;
  } catch (error) {
    console.error('Error creating app key:', error.response.data);
  }
};

Step 2: Create App Token

Generate a temporary access token using your app key. This token is required for all subsequent API calls.

Tokens expire after one hour. You must generate a new token when the previous one expires.

Endpoint

POST /auth/token

Request Headers

Header	Value	Description
`x-api-key`	Your API key	Provided during onboarding
`Content-Type`	`application/json`	Standard REST header

Request Body

{
  "data": {
    "type": "auth",
    "attributes": {
      "appKey": "your-app-key-from-step-1"
    }
  }
}

Request Parameters

Parameter	Type	Required	Description
`data`	object	Yes	Container for API data
`data.type`	string	Yes	Must be “auth”
`data.attributes`	object	Yes	Container for authentication attributes
`data.attributes.appKey`	string	Yes	The app key from Step 1

Response

{
  "links": {
    "self": "https://api.digitzs.com/auth/token"
  },
  "data": {
    "type": "auth",
    "id": "your-api-key",
    "attributes": {
      "appToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

Response Parameters

Parameter	Type	Description
`data.id`	string	Your API key
`data.attributes.appToken`	string	The access token to use in Authorization header

Code Examples

const axios = require('axios');

const createAppToken = async (appKey) => {
  try {
    const response = await axios.post(
      'https://api.digitzs.com/auth/token',
      {
        data: {
          type: 'auth',
          attributes: {
            appKey: appKey
          }
        }
      },
      {
        headers: {
          'x-api-key': 'your-api-key',
          'Content-Type': 'application/json'
        }
      }
    );

    const appToken = response.data.data.attributes.appToken;
    console.log('App Token:', appToken);
    return appToken;
  } catch (error) {
    console.error('Error creating app token:', error.response.data);
  }
};

Step 3: Making Authenticated Requests

Once you have an app token, include it in all API requests using the required headers.

Required Headers for API Calls

Header	Value	Description
`Authorization`	`Bearer {appToken}`	Your access token with “Bearer ” prefix
`x-api-key`	Your API key	Your API key from onboarding
`appId`	Your application ID	Your application ID from onboarding
`Content-Type`	`application/json`	Standard REST header

The Authorization header value must be formatted as Bearer {token} with:

A capital “B” in “Bearer”
A space between “Bearer” and your token

Example Authenticated Request

const axios = require('axios');

const makeAuthenticatedRequest = async (appToken) => {
  try {
    const response = await axios.get(
      'https://api.digitzs.com/merchants',
      {
        headers: {
          'Authorization': `Bearer ${appToken}`,
          'x-api-key': 'your-api-key',
          'appId': 'your-application-id',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Response:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

Token Management

Token Expiration

App tokens expire after one hour from creation. When a token expires, you will receive a 401 Unauthorized error.

Refreshing Tokens

To refresh an expired token, simply call the /auth/token endpoint again with your app key. You do not need to regenerate the app key unless you want to invalidate all existing tokens.

Best Practices

Store Securely

Store your API key and app key securely using environment variables or secret management services

Implement Retry Logic

Automatically refresh tokens when you receive a 401 error

Cache Tokens

Cache tokens and reuse them until they expire to reduce API calls

Monitor Expiration

Track token creation time and proactively refresh before expiration

Complete Authentication Example

Here’s a complete example that handles the full authentication flow:

const axios = require('axios');

class DigitzsAuth {
  constructor(apiKey, appId) {
    this.apiKey = apiKey;
    this.appId = appId;
    this.appKey = null;
    this.appToken = null;
    this.tokenExpiry = null;
    this.baseURL = 'https://api.digitzs.com';
  }

  async initialize() {
    this.appKey = await this.createAppKey();
    await this.refreshToken();
  }

  async createAppKey() {
    const response = await axios.post(
      `${this.baseURL}/auth/key`,
      {
        data: {
          type: 'auth',
          attributes: { appId: this.appId }
        }
      },
      {
        headers: {
          'x-api-key': this.apiKey,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data.data.attributes.appKey;
  }

  async refreshToken() {
    const response = await axios.post(
      `${this.baseURL}/auth/token`,
      {
        data: {
          type: 'auth',
          attributes: { appKey: this.appKey }
        }
      },
      {
        headers: {
          'x-api-key': this.apiKey,
          'Content-Type': 'application/json'
        }
      }
    );

    this.appToken = response.data.data.attributes.appToken;
    this.tokenExpiry = Date.now() + (55 * 60 * 1000); // 55 minutes
  }

  async getHeaders() {
    // Check if token needs refresh (5 min buffer)
    if (!this.appToken || Date.now() >= this.tokenExpiry) {
      await this.refreshToken();
    }

    return {
      'Authorization': `Bearer ${this.appToken}`,
      'x-api-key': this.apiKey,
      'appId': this.appId,
      'Content-Type': 'application/json'
    };
  }

  async request(method, endpoint, data = null) {
    const headers = await this.getHeaders();
    const config = {
      method,
      url: `${this.baseURL}${endpoint}`,
      headers
    };

    if (data) {
      config.data = data;
    }

    try {
      const response = await axios(config);
      return response.data;
    } catch (error) {
      if (error.response?.status === 401) {
        // Token expired, refresh and retry
        await this.refreshToken();
        headers.Authorization = `Bearer ${this.appToken}`;
        config.headers = headers;
        const retryResponse = await axios(config);
        return retryResponse.data;
      }
      throw error;
    }
  }
}

// Usage
(async () => {
  const auth = new DigitzsAuth('your-api-key', 'your-app-id');
  await auth.initialize();

  // Now you can make requests
  const merchants = await auth.request('GET', '/merchants');
  console.log(merchants);
})();

Troubleshooting

401 Unauthorized Error

This error occurs when:

Your token has expired (tokens last 1 hour)
The Authorization header is not properly formatted
Your API key or app ID is incorrect

Solution: Generate a new token and ensure the Authorization header uses the format Bearer {token} with a capital “B” and a space.

403 Forbidden Error

This error indicates:

Your account is not authorized to access the requested resource
Your API key has been revoked or suspended

Solution: Contact Digitzs support to verify your account status and permissions.

Invalid App Key

If you receive an error when creating a token:

Your app key may have been regenerated
The app key was not properly stored from Step 1

Solution: Regenerate the app key using /auth/key and try again.

Missing Headers

All authenticated requests require three headers:

Authorization: Bearer {token}
x-api-key: {your-api-key}
appId: {your-app-id}

Solution: Ensure all three headers are included in every request.

Security Best Practices

Never Expose Keys

Never commit API keys or tokens to version control or expose them in client-side code

Use Environment Variables

Store credentials in environment variables or secure secret management systems

Rotate Keys Regularly

Periodically regenerate your app keys to maintain security

Use HTTPS Only

Always make requests over HTTPS to encrypt data in transit

Next Steps

Now that you understand authentication, you’re ready to start using the API:

Create a Merchant

Set up merchant accounts

Process Payments

Start accepting payments

View Error Codes

Handle errors properly

Getting Started

​Overview

​Before You Begin

API Key

Application ID

​Authentication Flow

​Step 1: Generate App Key

​Endpoint

​Request Headers

​Request Body

​Request Parameters

​Response

​Response Parameters

​Code Examples

​Step 2: Create App Token

​Endpoint

​Request Headers

​Request Body

​Request Parameters

​Response

​Response Parameters

​Code Examples

​Step 3: Making Authenticated Requests

​Required Headers for API Calls

​Example Authenticated Request

​Token Management

​Token Expiration

​Refreshing Tokens

​Best Practices

Store Securely

Implement Retry Logic

Cache Tokens

Monitor Expiration

​Complete Authentication Example

​Troubleshooting

​Security Best Practices

Never Expose Keys

Use Environment Variables

Rotate Keys Regularly

Use HTTPS Only

​Next Steps

Create a Merchant

Process Payments

View Error Codes

Overview

Before You Begin

Authentication Flow

Step 1: Generate App Key

Endpoint

Request Headers

Request Body

Request Parameters

Response

Response Parameters

Code Examples

Step 2: Create App Token

Endpoint

Request Headers

Request Body

Request Parameters

Response

Response Parameters

Code Examples

Step 3: Making Authenticated Requests

Required Headers for API Calls

Example Authenticated Request

Token Management

Token Expiration

Refreshing Tokens

Best Practices

Complete Authentication Example

Troubleshooting

Security Best Practices

Next Steps