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>"
}
'import requests
url = "https://api.example.com/auth/token"
payload = {
"data": {},
"data.type": "<string>",
"data.attributes": {},
"data.attributes.appKey": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
data: {},
'data.type': '<string>',
'data.attributes': {},
'data.attributes.appKey': '<string>'
})
};
fetch('https://api.example.com/auth/token', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/auth/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
],
'data.type' => '<string>',
'data.attributes' => [
],
'data.attributes.appKey' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/auth/token"
payload := strings.NewReader("{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/auth/token")
.header("Content-Type", "application/json")
.body("{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/auth/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"errors": [
{
"status": "400",
"title": "Bad Request",
"detail": "The appKey field is required"
}
]
}
{
"errors": [
{
"status": "401",
"title": "Unauthorized",
"detail": "Invalid app key"
}
]
}
{
"errors": [
{
"status": "403",
"title": "Forbidden",
"detail": "The account is not authorized"
}
]
}
Authorization
Create App Token
Generate a temporary access token for authenticating API requests
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>"
}
'import requests
url = "https://api.example.com/auth/token"
payload = {
"data": {},
"data.type": "<string>",
"data.attributes": {},
"data.attributes.appKey": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
data: {},
'data.type': '<string>',
'data.attributes': {},
'data.attributes.appKey': '<string>'
})
};
fetch('https://api.example.com/auth/token', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/auth/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
],
'data.type' => '<string>',
'data.attributes' => [
],
'data.attributes.appKey' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/auth/token"
payload := strings.NewReader("{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/auth/token")
.header("Content-Type", "application/json")
.body("{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/auth/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {},\n \"data.type\": \"<string>\",\n \"data.attributes\": {},\n \"data.attributes.appKey\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"errors": [
{
"status": "400",
"title": "Bad Request",
"detail": "The appKey field is required"
}
]
}
{
"errors": [
{
"status": "401",
"title": "Unauthorized",
"detail": "Invalid app key"
}
]
}
{
"errors": [
{
"status": "403",
"title": "Forbidden",
"detail": "The account is not authorized"
}
]
}
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 thex-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
Container for API data
Must be
"auth"Container for authentication attributes
The app key obtained from
/auth/key endpointExample Request
{
"data": {
"type": "auth",
"attributes": {
"appKey": "your-app-key-from-auth-key-endpoint"
}
}
}
Response
Success Response (201 Created)
Contains URLs related to the resource
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"
}
}
}'
const axios = require('axios');
async function createAppToken(appKey) {
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;
const expiresAt = Date.now() + (60 * 60 * 1000); // 1 hour from now
console.log('App Token:', appToken);
console.log('Expires at:', new Date(expiresAt).toISOString());
return { appToken, expiresAt };
}
// Usage
createAppToken('your-app-key');
import requests
from datetime import datetime, timedelta
def create_app_token(app_key):
url = "https://api.digitzs.com/auth/token"
headers = {
"x-api-key": "your-api-key",
"Content-Type": "application/json"
}
payload = {
"data": {
"type": "auth",
"attributes": {
"appKey": app_key
}
}
}
response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
app_token = response.json()["data"]["attributes"]["appToken"]
expires_at = datetime.now() + timedelta(hours=1)
print(f"App Token: {app_token}")
print(f"Expires at: {expires_at.isoformat()}")
return {
"app_token": app_token,
"expires_at": expires_at
}
# Usage
create_app_token("your-app-key")
<?php
function createAppToken($appKey) {
$url = "https://api.digitzs.com/auth/token";
$headers = [
"x-api-key: your-api-key",
"Content-Type: application/json"
];
$payload = json_encode([
"data" => [
"type" => "auth",
"attributes" => [
"appKey" => $appKey
]
]
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
$data = json_decode($response, true);
$appToken = $data["data"]["attributes"]["appToken"];
$expiresAt = date('Y-m-d H:i:s', strtotime('+1 hour'));
echo "App Token: " . $appToken . "\n";
echo "Expires at: " . $expiresAt . "\n";
return [
"appToken" => $appToken,
"expiresAt" => $expiresAt
];
} else {
throw new Exception("Error creating app token: " . $response);
}
}
createAppToken("your-app-key");
?>
require 'net/http'
require 'json'
require 'uri'
def create_app_token(app_key)
uri = URI('https://api.digitzs.com/auth/token')
request = Net::HTTP::Post.new(uri)
request['x-api-key'] = 'your-api-key'
request['Content-Type'] = 'application/json'
request.body = {
data: {
type: 'auth',
attributes: {
appKey: app_key
}
}
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
if response.code == '201'
data = JSON.parse(response.body)
app_token = data['data']['attributes']['appToken']
expires_at = Time.now + (60 * 60) # 1 hour from now
puts "App Token: #{app_token}"
puts "Expires at: #{expires_at.iso8601}"
{
app_token: app_token,
expires_at: expires_at
}
else
raise "Error creating app token: #{response.body}"
end
end
create_app_token('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"
}
]
}
{
"errors": [
{
"status": "401",
"title": "Unauthorized",
"detail": "Invalid app key"
}
]
}
{
"errors": [
{
"status": "403",
"title": "Forbidden",
"detail": "The account is not authorized"
}
]
}
Common Error Scenarios
Invalid app key
Invalid app key
Error: 401 UnauthorizedSolution: Verify your app key is correct. If you’ve regenerated your app key, use the new one.
Expired app key
Expired app key
Error: 401 UnauthorizedSolution: Generate a new app key using the
/auth/key endpoint.Token expired during use
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
⌘I

