Validate Access Token

curl --request GET \
  --url https://api.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.oneclickdz.com/v3/validate', 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.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "username": "<string>",
    "apiKey": {
      "key": "<string>",
      "isEnabled": true,
      "type": "<string>",
      "allowedips": [
        {}
      ],
      "scope": "<string>"
    }
  }
}

GET

validate

Validate Access Token

curl --request GET \
  --url https://api.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: <api-key>'

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.oneclickdz.com/v3/validate', 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.oneclickdz.com/v3/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.oneclickdz.com/v3/validate"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Access-Token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.oneclickdz.com/v3/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "username": "<string>",
    "apiKey": {
      "key": "<string>",
      "isEnabled": true,
      "type": "<string>",
      "allowedips": [
        {}
      ],
      "scope": "<string>"
    }
  }
}

Overview

The validate endpoint allows you to verify that your API key is valid and retrieve information about the associated account and key permissions.

This endpoint is useful for verifying API key validity during application startup or after key rotation.

Response

boolean

required

true if validation succeeded

object

required

Show properties

string

Username associated with the API key

object

API key details

Show properties

string

Your API key

boolean

Whether the key is currently active

string

Key type: "SANDBOX" or "PRODUCTION"

array

Array of whitelisted IP addresses, empty [] means all IPs allowed.

string

Access level: "READ-WRITE" or "READ-ONLY"

Example Request

curl --request GET \
  --url https://api.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: YOUR_API_KEY'

const response = await fetch("https://api.oneclickdz.com/v3/validate", {
  headers: {
    "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
  },
});

const data = await response.json();

if (data.success) {
  console.log("✓ API key is valid");
  console.log("Account:", data.data.username);
  console.log("Type:", data.data.apiKey.type);
} else {
  console.error("✗ API key validation failed");
}

import requests
import os

response = requests.get(
    'https://api.oneclickdz.com/v3/validate',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

data = response.json()

if data['success']:
    print('✓ API key is valid')
    print(f"Account: {data['data']['username']}")
    print(f"Type: {data['data']['apiKey']['type']}")
else:
    print('✗ API key validation failed')

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.oneclickdz.com/v3/validate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data['success']) {
    echo "✓ API key is valid\n";
    echo "Account: " . $data['data']['username'] . "\n";
    echo "Type: " . $data['data']['apiKey']['type'] . "\n";
} else {
    echo "✗ API key validation failed\n";
}
?>

Example Response

{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "key": "ea27b376-9f5c-4b09-883f-1b96cd7b541c",
      "isEnabled": true,
      "type": "SANDBOX",
      "allowedips": [],
      "scope": "READ-WRITE"
    }
  }
}

Error Responses

400 - Missing Access Token

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Access token is required"
  },
  "requestId": "req_abc123"
}

401 - Invalid Access Token

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid",
    "details": {
      "attemptsLeft": 3
    }
  },
  "requestId": "req_abc123"
}

After 5 failed attempts, your IP will be temporarily blocked for 15 minutes.

403 - IP Blocked

{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to too many invalid attempts"
  },
  "requestId": "req_abc123"
}

Use Cases

Startup Validation

Verify API key during application initialization

Health Checks

Include in application health check routines

Environment Verification

Confirm you’re using the correct key (sandbox vs production)

Permission Checking

Verify key scope and permissions before operations

Integration Example

class OneClickDzClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://api.oneclickdz.com";
    this.validated = false;
  }

  async validate() {
    const response = await fetch(`${this.baseUrl}/v3/validate`, {
      headers: { "X-Access-Token": this.apiKey },
    });

    const data = await response.json();

    if (!data.success) {
      throw new Error(`API key validation failed: ${data.error.message}`);
    }

    this.username = data.data.username;
    this.keyType = data.data.apiKey.type;
    this.scope = data.data.apiKey.scope;
    this.validated = true;

    console.log(`✓ Authenticated as ${this.username} (${this.keyType})`);

    return data.data;
  }

  async request(endpoint, options = {}) {
    if (!this.validated) {
      await this.validate();
    }

    // Check if operation requires write access
    if (
      options.method &&
      options.method !== "GET" &&
      this.scope === "READ-ONLY"
    ) {
      throw new Error("This operation requires READ-WRITE access");
    }

    return fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        ...options.headers,
        "X-Access-Token": this.apiKey,
      },
    });
  }
}

// Usage
const client = new OneClickDzClient(process.env.ONECLICKDZ_API_KEY);
await client.validate();

// Now make requests
const response = await client.request("/v3/account/balance");

Best Practices

Validate on Startup

Always validate your API key when your application starts

// During app initialization
async function initializeApp() {
  try {
    await client.validate();
    console.log('✓ API client initialized');
  } catch (error) {
    console.error('✗ Failed to initialize API client:', error);
    process.exit(1);
  }
}

Cache Validation Result

Don’t validate on every request - cache the result

let validationCache = {
  validated: false,
  timestamp: 0,
  data: null
};

async function getValidatedClient() {
  const now = Date.now();
  const cacheExpiry = 5 * 60 * 1000; // 5 minutes
  
  if (validationCache.validated && (now - validationCache.timestamp) < cacheExpiry) {
    return validationCache.data;
  }
  
  const response = await fetch('https://api.oneclickdz.com/v3/validate', {
    headers: { 'X-Access-Token': API_KEY }
  });
  
  const data = await response.json();
  
  if (data.success) {
    validationCache = {
      validated: true,
      timestamp: now,
      data: data.data
    };
  }
  
  return data.data;
}

Check Environment

Verify you’re using the correct environment

const data = await validateApiKey();

const isProduction = process.env.NODE_ENV === 'production';
const keyType = data.apiKey.type;

if (isProduction && keyType === 'SANDBOX') {
  throw new Error('⚠️ Using SANDBOX key in production environment!');
}

if (!isProduction && keyType === 'PRODUCTION') {
  console.warn('⚠️ Using PRODUCTION key in development environment!');
}

Handle Gracefully

Implement proper error handling

async function validateWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://api.oneclickdz.com/v3/validate', {
        headers: { 'X-Access-Token': API_KEY }
      });
      
      const data = await response.json();
      
      if (data.success) {
        return data.data;
      }
      
      if (data.error.code === 'INVALID_ACCESS_TOKEN') {
        throw new Error('Invalid API key - check your configuration');
      }
      
      if (data.error.code === 'IP_BLOCKED') {
        throw new Error('IP blocked - too many failed attempts');
      }
      
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Health Check

Check API service status

Get Balance

Check your account balance

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Validate Access Token

Overview

Response

Example Request

Example Response

Error Responses

Use Cases

Startup Validation

Health Checks

Environment Verification

Permission Checking

Integration Example

Best Practices

Health Check

Get Balance

​Overview

​Response

​Example Request

​Example Response

​Error Responses

​Use Cases

Startup Validation

Health Checks

Environment Verification

Permission Checking

​Integration Example

​Best Practices

​Related Endpoints

Health Check

Get Balance

Overview

Response

Example Request

Example Response

Error Responses

Use Cases

Integration Example

Best Practices

Related Endpoints