Skip to main content

​
Overview

The Authorization endpoints handle authentication and authorization for the Digitzs API. A two-step process is required:
  1. Generate an app key using your API credentials
  2. Create an access token using the app key
Access tokens expire after one hour and must be refreshed regularly.

​
Authorization Flow

​
Endpoints

Create API Key

Generate an app key for token creationPOST /auth/key

Create App Token

Generate an access token (expires in 1 hour)POST /auth/token

​
Quick Start

​
Step 1: Create App Key

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

​
Step 2: Create App Token

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": "app-key-from-step-1"
      }
    }
  }'

​
Step 3: Use Token in 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"

​
Best Practices

Store your API key and app key securely:
  • Use environment variables
  • Never commit credentials to version control
  • Use secret management services in production
Cache access tokens and reuse them:
  • Tokens are valid for 1 hour
  • Track token expiration time
  • Refresh tokens proactively before expiration
Implement robust error handling:
  • Catch 401 errors and refresh tokens automatically
  • Implement retry logic with exponential backoff
  • Log authentication failures for monitoring
Rotate app keys periodically:
  • Creating a new app key invalidates the old one
  • Plan key rotation during low-traffic periods
  • Update all services using the old key

​
Common Issues

Token Format: The Authorization header must be formatted as Bearer {token} with:
  • A capital “B” in “Bearer”
  • A space between “Bearer” and your token
Token Expiration: Implement automatic token refresh 5 minutes before expiration to avoid service interruptions.

​
Security Considerations

HTTPS Only

Always use HTTPS for API requests to protect credentials in transit

Credential Rotation

Rotate API keys and app keys regularly as part of security best practices

Limited Scope

Use separate API keys for different environments (dev, staging, production)

Monitoring

Monitor authentication failures and unusual access patterns

​
Next Steps

1

Get Credentials

Contact Digitzs to receive your API key and application ID
2

Test Authentication

Follow the quick start guide to test the authentication flow
3

Implement Token Management

Build token caching and refresh logic into your application
4

Start Using the API

Begin making authenticated requests to other endpoints

​
Additional Resources

Authentication Guide

Detailed authentication tutorial with code examples

Error Codes

Handle authentication errors properly