Create App Token

Generate a temporary access token for authenticating API requests

Endpoint

POST https://api.digitzs.com/auth/token

Overview

Use this endpoint to generate a temporary access token (app token) using your app key. This token is required for all subsequent API calls and expires after one hour.

Tokens expire after one hour. Implement token refresh logic to avoid authentication failures.

Authentication

This endpoint requires the x-api-key header but not a Bearer token.

Header	Value	Required
x-api-key	Your API key from onboarding	Yes
Content-Type	application/json	Yes

Request Body

data · object · required

Container for API data

data.type · string · required

Must be "auth"

data.attributes · object · required

Container for authentication attributes

data.attributes.appKey · string · required

The app key obtained from /auth/key endpoint

Example Request

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

Response

Success Response (201 Created)

links · object

Contains URLs related to the resource

data · object

Container for response data

Show properties

data.type · string

Resource type - will be "auth"

data.id · string

Your API key

data.attributes.appToken · string

The access token to use in your API requests. This token expires after 1 hour.

Use this token in the Authorization header as: Bearer {appToken}

Example Response

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

Using the Token

Include the token in all authenticated API requests:

curl -X GET https://api.digitzs.com/merchants \
  -H "Authorization: Bearer your-app-token" \
  -H "x-api-key: your-api-key" \
  -H "appId: your-app-id"

The Authorization header must be formatted as Bearer {token} with a capital “B” and a space between “Bearer” and your token.

Code Examples

cURL

curl -X POST https://api.digitzs.com/auth/token \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "auth",
      "attributes": {
        "appKey": "your-app-key"
      }
    }
  }'

Token Management

Automatic Refresh

Implement automatic token refresh logic to avoid authentication failures:

class TokenManager {
  constructor(apiKey, appKey) {
    this.apiKey = apiKey;
    this.appKey = appKey;
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    // Refresh if token is missing or expires in less than 5 minutes
    const refreshBuffer = 5 * 60 * 1000; // 5 minutes
    const shouldRefresh = !this.token || Date.now() >= (this.expiresAt - refreshBuffer);

    if (shouldRefresh) {
      await this.refreshToken();
    }

    return this.token;
  }

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

    this.token = response.data.data.attributes.appToken;
    this.expiresAt = Date.now() + (60 * 60 * 1000); // 1 hour
  }
}

// Usage
const tokenManager = new TokenManager('your-api-key', 'your-app-key');
const token = await tokenManager.getToken(); // Automatically refreshes if needed

Error Responses

400 Bad Request

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The appKey field is required"
    }
  ]
}

Common Error Scenarios

Invalid app key

Error: 401 Unauthorized

Solution: Verify your app key is correct. If you’ve regenerated your app key, use the new one.

Expired app key

Error: 401 Unauthorized

Solution: Generate a new app key using the /auth/key endpoint.

Token expired during use

Error: 401 Unauthorized (from other endpoints)

Solution: Catch 401 errors and automatically refresh the token before retrying the request.

Best Practices

Cache Tokens

Store and reuse tokens for their full 1-hour lifetime to minimize API calls

Proactive Refresh

Refresh tokens 5 minutes before expiration to avoid service interruptions

Handle 401 Errors

Implement automatic token refresh on 401 responses

Monitor Expiration

Track token expiration time and log refresh events

Next Steps

Now that you have an access token, you can start making authenticated API requests:

Create Merchant

Set up merchant accounts

Process Payment

Accept payments

List Merchants

Retrieve merchant data