AkuWorks Logo

AkuWorks

API Quick Start

API Quick Start Guide

Get started with AkuWorks API in minutes. This guide will walk you through setting up your first integration with code examples and best practices.

Prerequisites

Before you start, make sure you have:

AkuWorks account with a configured Discord server
Basic knowledge of REST APIs and HTTP requests
Development environment (Node.js, Python, or similar)
HTTPS endpoint for webhook testing (optional)

Step 1: Get Your API Key

Generate API Key

First, you'll need to generate an API key from your AkuWorks dashboard:

  1. 1Log in to your AkuWorks dashboard
  2. 2Navigate to Settings → API Keys
  3. 3Click "Generate New API Key"
  4. 4Copy and securely store your API key

Step 2: Make Your First Request

Test API Connection

Let's start by getting information about your server:

cURL Example

curl -X GET "https://api.akuworks.com/v1/servers/YOUR_SERVER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript/Node.js Example

const fetch = require('node-fetch');

const apiKey = 'YOUR_API_KEY';
const serverId = 'YOUR_SERVER_ID';

async function getServerInfo() {
  try {
    const response = await fetch(`https://api.akuworks.com/v1/servers/${serverId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    console.log('Server Info:', data);
  } catch (error) {
    console.error('Error:', error);
  }
}

getServerInfo();

Python Example

import requests

api_key = 'YOUR_API_KEY'
server_id = 'YOUR_SERVER_ID'

def get_server_info():
    url = f'https://api.akuworks.com/v1/servers/{server_id}'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()
        print('Server Info:', data)
    except requests.exceptions.RequestException as e:
        print('Error:', e)

get_server_info()

Expected Response

{
  "id": "123456789012345678",
  "name": "My Discord Server",
  "verification_enabled": true,
  "stats": {
    "total_verifications": 1250,
    "verifications_today": 45,
    "success_rate": 98.5
  },
  "settings": {
    "verification_method": "turnstile",
    "rate_limiting": true,
    "bot_detection": true
  }
}

Step 3: Initiate User Verification

Start Verification Process

Now let's initiate a verification for a Discord user:

JavaScript Example

async function initiateVerification(userId) {
  try {
    const response = await fetch(`https://api.akuworks.com/v1/servers/${serverId}/verify`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        user_id: userId,
        method: 'turnstile',
        redirect_url: 'https://yourapp.com/verification-complete'
      })
    });
    
    const data = await response.json();
    console.log('Verification URL:', data.verification_url);
    return data.verification_url;
  } catch (error) {
    console.error('Error:', error);
  }
}

// Usage
const verificationUrl = await initiateVerification('987654321098765432');
// Redirect user to verificationUrl

Response

{
  "verification_id": "ver_abc123def456",
  "verification_url": "https://verify.akuworks.com/v/abc123def456",
  "expires_at": "2025-01-25T11:00:00Z",
  "status": "pending"
}

Step 4: Handle Webhook Events (Optional)

Receive Real-time Events

Set up webhooks to receive real-time notifications about verification events:

Express.js Webhook Handler

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-akuworks-signature'];
  const payload = req.body;
  
  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload, 'utf8')
    .digest('hex');
  
  if (signature !== `sha256=${expectedSignature}`) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.event) {
    case 'verification.success':
      console.log('User verified:', event.user.id);
      // Update your database, send notifications, etc.
      break;
      
    case 'verification.failed':
      console.log('Verification failed:', event.user.id, event.reason);
      // Handle failed verification
      break;
      
    default:
      console.log('Unknown event:', event.event);
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Error Handling Best Practices

Always implement proper error handling in your API integrations:

async function makeAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    if (error.name === 'TypeError') {
      console.error('Network error:', error.message);
    } else {
      console.error('API error:', error.message);
    }
    throw error;
  }
}

Common HTTP Status Codes:

  • • 200 - Success
  • • 400 - Bad Request (invalid parameters)
  • • 401 - Unauthorized (invalid API key)
  • • 429 - Rate Limited
  • • 500 - Server Error

Next Steps

Great! You've successfully made your first API calls. Here's what to explore next: