Skip to main content

​
Overview

KillB API uses JWT (JSON Web Tokens) for authentication. All API requests must include a valid access token in the Authorization header.
API authentication uses a combination of email/password login and API keys for different access patterns.

​
Authentication Methods

Used for most API operations. Obtained via login endpoint.Best for: Web and mobile applications, user-specific operations

​
Getting Your Credentials

  1. Sign up for a KillB account at https://otc.killb.com/auth/jwt/register
  2. Access Portal at otc.killb.com
  3. Get Credentials:
    • Your login email and password
    • Your API key from the portal settings

​
Login Flow

​
Step 1: Generate Access Token

POST /api/v2/auth/login
Request: 
{
  "email": "[email protected]",
  "password": "your-password"
}
Response: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600000,
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

curl --request POST \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "password": "your-password"
  }'

​
Step 2: Use Access Token

Include the access token in the Authorization header for all API requests: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Example Request: 
curl --request GET \
  --url https://teste-94u93qnn.uc.gateway.dev/api/v2/users \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token: 
POST /api/v2/auth/refresh
Request: 
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Response: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600000
}

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://teste-94u93qnn.uc.gateway.dev/api/v2/auth/refresh', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ refreshToken })
  });
  
  const data = await response.json();
  return data.accessToken;
}
Implement automatic token refresh in your application to maintain uninterrupted API access.

​
Security Best Practices

  • Never commit credentials to version control
  • Use environment variables for API keys and tokens
  • Rotate API keys regularly
  • Use secrets management services (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Store tokens securely (encrypted storage, secure cookies)
  • Implement automatic token refresh
  • Clear tokens on logout
  • Set appropriate token expiration times
  • Always use HTTPS for API requests
  • Implement certificate pinning for mobile apps
  • Validate SSL certificates
  • Use secure network connections
  • Don’t expose authentication errors to end users
  • Log authentication failures for monitoring
  • Implement rate limiting on login attempts
  • Handle token expiration gracefully

​
Authentication Errors

Common authentication error responses:
Status CodeErrorDescription
401UnauthorizedInvalid or expired token
403ForbiddenValid token but insufficient permissions
400Bad RequestInvalid credentials format
Example Error Response: 
{
  "errorCode": "AUTH.0001",
  "message": ["Invalid credentials"],
  "statusCode": "401"
}

​
Testing Authentication

Use the sandbox environment to test authentication: Sandbox URL: https://teste-94u93qnn.uc.gateway.dev
Create a separate test account for sandbox testing. Sandbox credentials won’t work in production.

​
Example: Complete Auth Flow

Here’s a complete example managing authentication state: 
class KillBAuth {
  constructor(email, password) {
    this.email = email;
    this.password = password;
    this.accessToken = null;
    this.refreshToken = null;
    this.baseUrl = 'https://teste-94u93qnn.uc.gateway.dev';
  }

  async login() {
    const response = await fetch(`${this.baseUrl}/api/v2/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: this.email,
        password: this.password
      })
    });

    const data = await response.json();
    this.accessToken = data.accessToken;
    this.refreshToken = data.refreshToken;
    return data;
  }

  async refresh() {
    const response = await fetch(`${this.baseUrl}/api/v2/auth/refresh`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        refreshToken: this.refreshToken
      })
    });

    const data = await response.json();
    this.accessToken = data.accessToken;
    this.refreshToken = data.refreshToken;
    return data;
  }

  getAuthHeaders() {
    return {
      'Authorization': `Bearer ${this.accessToken}`,
      'Content-Type': 'application/json'
    };
  }
}

// Usage
const auth = new KillBAuth('[email protected]', 'your-password');
await auth.login();

// Make authenticated request
const response = await fetch(`${auth.baseUrl}/api/v2/users`, {
  headers: auth.getAuthHeaders()
});

​
Next Steps

Supported Networks

Learn about available payment methods and blockchain networks

Create Your First User

Start building by creating user profiles