Skip to main content

Authentication

Axol API uses API keys for REST endpoints and JWT tokens for WebSocket connections.

Getting Your API Key​

  1. Sign up at app.axol.io
  2. Navigate to Dashboard -> API Keys
  3. Click Create New Key
  4. Copy and secure your key immediately
Keep Your API Key Secret
  • Never commit keys to version control
  • Don't share keys between environments
  • Don't use API keys in client-side code
  • Rotate keys regularly

REST API Authentication​

Include your API key in the X-API-Key header:

curl https://api.axol.io/api/v1/blockchain/ethereum/gas \
  -H "X-API-Key: YOUR_API_KEY"

Python:

import requests

response = requests.get(
    "https://api.axol.io/api/v1/blockchain/ethereum/gas",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

TypeScript:

const response = await fetch('https://api.axol.io/api/v1/blockchain/ethereum/gas', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

Bearer Token (Alternative)​

For OAuth-style authentication:

curl https://api.axol.io/api/v1/blockchain/ethereum/gas \
  -H "Authorization: Bearer YOUR_API_KEY"
Both methods work identically

Choose based on your framework's conventions.

WebSocket Authentication​

WebSocket connections require JWT tokens, not API keys.

Step 1: Get JWT Token​

Exchange your API key for a JWT token:

curl -X POST https://api.axol.io/api/v1/auth/token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 2: Connect with JWT​

Pass the JWT token as a query parameter:

wss://api.axol.io/api/v1/ws/connect?token=eyJhbGciOiJIUzI1NiIs...

Python:

import asyncio
import websockets
import requests

# Get JWT token
auth_response = requests.post(
    "https://api.axol.io/api/v1/auth/token",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"grant_type": "client_credentials"}
)
jwt_token = auth_response.json()["access_token"]

# Connect WebSocket
async def connect():
    url = f"wss://api.axol.io/api/v1/ws/connect?token={jwt_token}"
    async with websockets.connect(url) as ws:
        message = await ws.recv()
        print(message)

asyncio.run(connect())

TypeScript:

// Get JWT token
const authResponse = await fetch('https://api.axol.io/api/v1/auth/token', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ grant_type: 'client_credentials' })
});

const { access_token } = await authResponse.json();

// Connect WebSocket
const ws = new WebSocket(`wss://api.axol.io/api/v1/ws/connect?token=${access_token}`);

Token Refresh​

JWT tokens expire after 1 hour. Implement refresh logic:

import time

class TokenManager:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self._token = None
        self._expires_at = 0

    def get_token(self) -> str:
        if time.time() >= self._expires_at - 60:  # Refresh 1 min early
            self._refresh_token()
        return self._token

    def _refresh_token(self):
        response = requests.post(
            "https://api.axol.io/api/v1/auth/token",
            headers={"X-API-Key": self.api_key},
            json={"grant_type": "client_credentials"}
        )
        data = response.json()
        self._token = data["access_token"]
        self._expires_at = time.time() + data["expires_in"]

Environment Variables​

Store credentials in environment variables:

# .env file
AXOL_API_KEY=your_api_key_here

Python:

import os

api_key = os.getenv('AXOL_API_KEY')

TypeScript:

const apiKey = process.env.AXOL_API_KEY;

API Key Scopes​

Control access with scopes when creating keys:

ScopeDescription
read:blockchainRead blockchain data
read:analyticsAccess analytics endpoints
write:alertsCreate and manage alerts
stream:websocketAccess WebSocket streams
admin:accountManage account settings
Principle of Least Privilege

Create separate API keys with minimal scopes for each use case.

Security Best Practices​

IP Whitelisting​

Restrict API key usage to specific IP addresses in your dashboard.

Key Rotation​

  1. Create a new API key
  2. Update your application
  3. Test thoroughly
  4. Delete the old key
Grace Period

Run both old and new keys in parallel for 24-48 hours during rotation.

Rate Limit Headers​

Monitor your usage via response headers:

X-RateLimit-CU-Limit: 2000000000
X-RateLimit-CU-Remaining: 1950000000
X-RateLimit-CU-Reset: 1704153600

Testing Your Connection​

REST API​

curl https://api.axol.io/api/v1/health \
  -H "X-API-Key: YOUR_API_KEY"

Expected response:

{
  "status": "healthy",
  "version": "1.0.0"
}

WebSocket​

# Get token
TOKEN=$(curl -s -X POST https://api.axol.io/api/v1/auth/token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials"}' | jq -r '.access_token')

# Connect (requires wscat)
wscat -c "wss://api.axol.io/api/v1/ws/connect?token=$TOKEN"

Error Codes​

401 Unauthorized​

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

Solutions:

  • Verify your API key is correct
  • Check if key has been revoked in dashboard
  • Ensure key has appropriate scopes

403 Forbidden​

{
  "error": "Insufficient permissions",
  "message": "This API key does not have the required scope"
}

Solutions:

  • Check key scopes in dashboard
  • Create new key with required permissions

WebSocket 1008 Policy Violation​

Connection closed: 1008 - Authentication required

Solutions:

  • Ensure JWT token is provided in query parameter
  • Check if JWT token has expired
  • Refresh JWT token and reconnect

See Also​