Skip to main content
POST
/
auth
/
token
Create App Token
curl --request POST \
  --url https://api.example.com/auth/token \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {},
  "data.type": "<string>",
  "data.attributes": {},
  "data.attributes.appKey": "<string>"
}
'
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The appKey field is required"
    }
  ]
}

​
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.
HeaderValueRequired
x-api-keyYour API key from onboardingYes
Content-Typeapplication/jsonYes

​
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

​
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 -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

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

​
Common Error Scenarios

Error: 401 UnauthorizedSolution: Verify your app key is correct. If you’ve regenerated your app key, use the new one.
Error: 401 UnauthorizedSolution: Generate a new app key using the /auth/key endpoint.
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