Authentication

Authentication

The UnboundBytes API supports multiple authentication methods to suit different use cases. This guide explains each method and when to use it.

Authentication Methods Overview

Method	Use Case	Security Level
Bearer Token	Web applications, portals	High
HMAC Signature	Agent communication	Very High
API Key	Scripts, automation	Medium

Bearer Token Authentication

Bearer tokens are JWT tokens issued by your identity provider (typically OIDC). This is the recommended method for web applications.

How It Works

1. User authenticates with your identity provider
2. Identity provider issues a JWT token
3. Include the token in the Authorization header
4. API validates the token and extracts user/tenant info

Request Format

GET /v1/devices HTTP/1.1
Host: api.unboundbytes.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

SDK Usage

import { UnboundBytesClient } from '@unboundbytes/sdk';

const client = new UnboundBytesClient({
  auth: {
    type: 'bearer',
    token: 'your-jwt-token'
  }
});

Token Refresh

The SDK supports automatic token refresh:

const client = new UnboundBytesClient({
  auth: {
    type: 'bearer',
    token: currentToken,
    expiresAt: Date.now() + 3600000, // Token expires in 1 hour
    refreshHandler: async () => {
      // Called automatically when token is near expiry
      const response = await fetch('/api/auth/refresh');
      const data = await response.json();
      return {
        token: data.accessToken,
        expiresAt: Date.now() + data.expiresIn * 1000
      };
    }
  }
});

HMAC Signature Authentication

HMAC authentication is required for agent-to-orchestrator communication. It provides cryptographic proof that requests are authentic and haven’t been tampered with.

How It Works

1. Agent generates a timestamp
2. Agent creates a message: body + timestamp
3. Agent signs the message with HMAC-SHA256 using the shared secret
4. Agent includes the signature and metadata in headers
5. API validates the signature and timestamp

Request Format

POST /v1/devices/dev_xxx/heartbeat HTTP/1.1
Host: api.unboundbytes.com
Content-Type: application/json
x-ub-agent-id: agt_xxx
x-ub-tenant-id: ten_xxx
x-ub-timestamp: 2025-01-01T00:00:00.000Z
x-ub-signature: 8f4a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a

{"status": "online", "metrics": {...}}

SDK Usage

import { UnboundBytesClient } from '@unboundbytes/sdk';

const client = new UnboundBytesClient({
  auth: {
    type: 'hmac',
    agentId: 'agt_xxx',
    tenantId: 'ten_xxx',
    sharedSecret: 'your-shared-secret'
  }
});

// The SDK automatically signs all requests
await client.sendHeartbeat('dev_xxx', {
  cpu: 25.5,
  memory: 4096,
  disk: 50000,
  timestamp: new Date().toISOString()
});

Signature Verification

The server verifies requests by:

1. Checking the timestamp is within 5 minutes of current time
2. Reconstructing the expected signature
3. Comparing signatures using constant-time comparison

Caution

HMAC signatures include a timestamp to prevent replay attacks. Ensure your system clock is synchronized.

Generating Signatures Manually

If not using the SDK, generate signatures like this:

import { createHmac } from 'crypto';

function generateSignature(body: string, timestamp: string, secret: string): string {
  const message = body + timestamp;
  return createHmac('sha256', secret)
    .update(message)
    .digest('hex');
}

// Example
const body = JSON.stringify({ status: 'online' });
const timestamp = new Date().toISOString();
const signature = generateSignature(body, timestamp, sharedSecret);

API Key Authentication

API keys provide a simpler authentication method for scripts and automation tools.

Request Format

GET /v1/devices HTTP/1.1
Host: api.unboundbytes.com
x-api-key: key_xxx
x-ub-tenant-id: ten_xxx
Content-Type: application/json

SDK Usage

import { UnboundBytesClient } from '@unboundbytes/sdk';

const client = new UnboundBytesClient({
  auth: {
    type: 'apikey',
    apiKey: 'key_xxx',
    tenantId: 'ten_xxx'
  }
});

Tip

API keys should be treated as secrets. Never commit them to source control or expose them in client-side code.

Security Best Practices

Token Storage

• Browser: Store tokens in memory or secure HTTP-only cookies
• Server: Use environment variables or secret management
• Never: Commit tokens to source control

Token Rotation

• Implement regular token refresh for long-running applications
• Rotate API keys periodically
• Revoke tokens immediately when compromised

Network Security

• Always use HTTPS
• Validate TLS certificates
• Use the latest TLS version (1.3 recommended)

Error Responses

401 Unauthorized

Missing or invalid authentication:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden

Valid authentication but insufficient permissions:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied to this resource"
  }
}

Invalid Signature

HMAC signature validation failed:

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Request signature is invalid"
  }
}

Next Steps

• API Overview - Explore the API structure
• API Explorer - Try the API interactively
• TypeScript SDK - Full SDK documentation