API Endpoints

API Endpoints

This page documents all ByteAuth API endpoints for custom integrations.

Base URLs

Environment	URL
Production	https://api.byteauth.com/v1
Sandbox	https://sandbox.byteauth.com/v1

Note

The SDK handles all API communication. These endpoints are for custom integrations only.

Authentication

All API requests require an API key in the header:

Authorization: Bearer ba_live_xxxxxxxxxxxxx

Endpoints

Generate Session

Creates a new authentication session with QR code data.

POST /sessions

Request Body:

{
  "domain": "example.com",
  "mode": "login",
  "webhook_url": "https://example.com/webhook/login",
  "metadata": {
    "return_url": "/dashboard",
    "custom_data": "any-string"
  }
}

Response:

{
  "id": "sess_abc123xyz789",
  "challenge": "byteauth:login:example.com:1699876543:nonce123",
  "qr_data": "byteauth://auth?webhook=...",
  "expires_at": "2024-11-15T10:30:00Z",
  "status": "pending",
  "created_at": "2024-11-15T10:29:30Z"
}

Status Codes:

Code	Description
201	Session created
400	Invalid request body
401	Invalid API key
422	Domain not registered

---

Get Session

Retrieves the current status of a session.

GET /sessions/{session_id}

Response (pending):

{
  "id": "sess_abc123xyz789",
  "status": "pending",
  "expires_at": "2024-11-15T10:30:00Z"
}

Response (authenticated):

{
  "id": "sess_abc123xyz789",
  "status": "authenticated",
  "authenticated_at": "2024-11-15T10:29:45Z",
  "user": {
    "public_key": "04a1b2c3d4e5f6...",
    "device_info": {
      "platform": "ios",
      "version": "2.1.0"
    }
  }
}

Status Codes:

Code	Description
200	Session found
404	Session not found
410	Session expired

---

Refresh Challenge

Generates a new challenge for an existing session.

POST /sessions/{session_id}/refresh

Response:

{
  "id": "sess_abc123xyz789",
  "challenge": "byteauth:login:example.com:1699876573:nonce456",
  "qr_data": "byteauth://auth?webhook=...",
  "expires_at": "2024-11-15T10:30:30Z"
}

---

Verify Signature

Verify a signature without processing authentication.

POST /verify

Request Body:

{
  "public_key": "04a1b2c3d4e5f6...",
  "signature": "3045022100...",
  "message": "byteauth:login:example.com:1699876543:nonce123"
}

Response:

{
  "valid": true,
  "public_key": "04a1b2c3d4e5f6...",
  "message_hash": "sha256:abc123..."
}

---

List Domains

List all registered domains for your account.

GET /domains

Response:

{
  "domains": [
    {
      "id": "dom_abc123",
      "domain": "example.com",
      "verified": true,
      "webhook_url": "https://example.com/webhook",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

---

Register Domain

Register a new domain for ByteAuth.

POST /domains

Request Body:

{
  "domain": "newsite.com",
  "webhook_url": "https://newsite.com/api/byteauth/webhook"
}

Response:

{
  "id": "dom_xyz789",
  "domain": "newsite.com",
  "verified": false,
  "verification_token": "byteauth-verify=abc123xyz",
  "webhook_url": "https://newsite.com/api/byteauth/webhook"
}

Note

Add the verification token as a TXT record to your DNS to verify domain ownership.

---

Verify Domain

Trigger domain verification check.

POST /domains/{domain_id}/verify

Response:

{
  "id": "dom_xyz789",
  "domain": "newsite.com",
  "verified": true,
  "verified_at": "2024-11-15T10:30:00Z"
}

Webhook Payloads

Login Webhook

Sent when a user authenticates:

{
  "event": "login",
  "timestamp": "2024-11-15T10:29:45Z",
  "session_id": "sess_abc123xyz789",
  "data": {
    "public_key": "04a1b2c3d4e5f6789...",
    "signature": "3045022100abc123...",
    "challenge": "byteauth:login:example.com:1699876543:nonce123",
    "signed_at": 1699876545,
    "device_info": {
      "platform": "ios",
      "version": "2.1.0",
      "device_id": "dev_abc123"
    }
  }
}

Registration Webhook

Sent when a new user registers:

{
  "event": "register",
  "timestamp": "2024-11-15T10:29:45Z",
  "session_id": "sess_abc123xyz789",
  "data": {
    "public_key": "04a1b2c3d4e5f6789...",
    "signature": "3045022100abc123...",
    "challenge": "byteauth:register:example.com:1699876543:nonce123",
    "signed_at": 1699876545,
    "device_info": {
      "platform": "android",
      "version": "2.1.0",
      "device_id": "dev_xyz789"
    }
  }
}

Webhook Verification

Verify webhook signatures to ensure authenticity:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-byteauth-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook...
});

Rate Limits

Endpoint	Rate Limit
POST /sessions	100/minute
GET /sessions/*	300/minute
POST /verify	200/minute
Webhooks	Unlimited (outbound)

Caution

Rate limits are per API key. Contact support for higher limits.

SDK Methods

These endpoints are wrapped by SDK methods:

Laravel

use ByteFederal\ByteAuthLaravel\ByteAuth;

// Generate session
$session = ByteAuth::createSession('login');

// Check session
$status = ByteAuth::getSession($sessionId);

// Verify signature
$valid = ByteAuth::verifySignature($publicKey, $signature, $message);

Next.js

import { createSession, getSession, verifySignature } from '@bytefederal/byteauth-nextjs';

// Generate session
const session = await createSession({ mode: 'login' });

// Check session
const status = await getSession(sessionId);

// Verify signature
const valid = await verifySignature(publicKey, signature, message);

Error Responses

All errors follow this format:

{
  "error": {
    "code": "invalid_signature",
    "message": "The provided signature does not match the message",
    "details": {
      "public_key": "04a1b2c3...",
      "expected_format": "DER-encoded ECDSA signature"
    }
  }
}

See Error Codes for a complete list.

Next Steps

• Error code reference
• Security best practices
• Authentication flow