Authentication API

Generate a JSON Web Token to authenticate your requests to Kamoa's protected services.

Prerequisites

You need valid client credentials to use this API. Don't have credentials? Contact our support team.

Quick Start

curl -X POST https://api.kamoa.io/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "secret": "your-client-secret"
  }'

Base URL

https://api.kamoa.io/auth

Generate Token

POST /auth/token

Obtain a JWT token for API authentication.

Request

POST /auth/token
Content-Type: application/json

{
  "clientId": "your-client-id",
  "secret": "your-client-secret"
}

Parameter	Type	Required	Description
clientId	string	✅	Your unique client identifier
secret	string	✅	Your client secret key

Responses

✅ Success (200)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using the token:

Authorization:  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

❌ Bad Request (400)

Missing fields:

{
  "message": "Missing required fields: clientId, secret"
}

Invalid credentials:

{
  "message": "Invalid credentials provided"
}

⚠️ Server Error (500)

{
  "message": "Unexpected error"
}

Code Examples

cURL

# Get token
curl -X POST https://api.kamoa.io/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "secret": "your-client-secret"
  }'

# Use token in subsequent requests
curl -X GET https://api.kamoa.io/protected-endpoint \
  -H "Authorization:  your-jwt-token"

JavaScript (Browser/Fetch)

// Async/await
async function getToken() {
  const response = await fetch('https://api.kamoa.io/auth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      clientId: 'your-client-id',
      secret: 'your-client-secret'
    })
  });
  
  const data = await response.json();
  return data.token;
}

// Using the token
const token = await getToken();
const apiResponse = await fetch('https://api.kamoa.io/protected-endpoint', {
  headers: {
    'Authorization': ` ${token}`
  }
});

Python

import requests

def get_token(client_id, secret):
    """Get JWT token from Kamoa API"""
    url = "https://api.kamoa.io/auth/token"
    payload = {
        "clientId": client_id,
        "secret": secret
    }
    
    response = requests.post(url, json=payload)
    response.raise_for_status()
    
    return response.json()["token"]

# Usage
token = get_token("your-client-id", "your-client-secret")

# Use token in requests
headers = {"Authorization": f" {token}"}
api_response = requests.get("https://api.kamoa.io/protected-endpoint", headers=headers)

Node.js

const axios = require('axios');

async function getToken(clientId, secret) {
  try {
    const response = await axios.post('https://api.kamoa.io/auth/token', {
      clientId,
      secret
    });
    
    return response.data.token;
  } catch (error) {
    console.error('Authentication failed:', error.response?.data?.message);
    throw error;
  }
}

// Usage
const token = await getToken('your-client-id', 'your-client-secret');

// Configure axios with token
const apiClient = axios.create({
  baseURL: 'https://api.kamoa.io',
  headers: {
    'Authorization': ` ${token}`
  }
});

Token Management

Token Lifecycle

• Expiration: JWT tokens have a limited lifespan (check the exp claim)
• Refresh: Generate a new token when the current one expires
• Validation: Tokens are cryptographically signed and verified server-side

Best Practices

Security Best Practices

• Never expose credentials in client-side code or version control
• Store tokens securely using HTTP-only cookies or secure storage
• Implement token refresh logic before expiration
• Use environment variables for credentials in production

// ✅ Good - Environment variables
const clientId = process.env.KAMOA_CLIENT_ID;
const secret = process.env.KAMOA_CLIENT_SECRET;

// ❌ Bad - Hardcoded credentials
const clientId = "abc123";
const secret = "secret123";

Troubleshooting

Common Issues

Issue	Cause	Solution
Missing required fields	Empty or missing clientId/secret	Verify both fields are included in request body
Invalid credentials	Wrong credentials or deactivated client	Check credentials or contact support
401 Unauthorized when using token	Expired or invalid token	Generate a new token
Network errors	Connectivity issues	Check internet connection and API status

Error Handling Example

async function authenticateWithRetry(clientId, secret, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.kamoa.io/auth/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ clientId, secret })
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`HTTP ${response.status}: ${error.message}`);
      }

      return await response.json();
    } catch (error) {
      console.warn(`Authentication attempt ${attempt} failed:`, error.message);
      
      if (attempt === maxRetries) {
        throw new Error(`Authentication failed after ${maxRetries} attempts: ${error.message}`);
      }
      
      // Wait before retry (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Support

Need help or want to request API credentials?

• 📧 Email: dev-support@kamoa.io
• 📋 Include: Your use case, expected request volume, and technical requirements
• ⏱️ Response time: Typically within 24 hours during business days

API Status

Check our status page for real-time API availability and maintenance updates.