Authentication

The Burn & Claim API uses a two-tier authentication model designed to keep your long-lived credentials safe on the server while giving browsers and mobile apps short-lived, scoped access.

API Key

API keys are long-lived credentials created in the Burn & Claim Dashboard. They are used server-side only to create session tokens and to make administrative API calls.

const server = new BurnerClient({
  apiKey: process.env.BURNER_API_KEY, // ak_live_...
})

The SDK sends the key as the X-Api-Key header on every request:

X-Api-Key: ak_live_abc123...

Never ship an API key to a browser or mobile app. If a key is compromised, revoke it immediately from the dashboard and create a new one.

Session Token

Session tokens are short-lived bearer tokens created by your backend via POST /sessions. Each token is bound to a single wallet address and a set of scopes.

const session = await server.createSession({
  walletAddress: 'So11111111111111111111111111111111111111112',
  scopes: ['wallet:read', 'transactions:build', 'transactions:submit'],
  ttlSeconds: 600,
})
// Forward session.token to your frontend

On the frontend, construct a client with the session token:

const client = new BurnerClient({
  sessionToken: session.token,
})

The SDK sends it as a standard Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

TTL

When a session expires, the client receives a 401 Unauthorized response. Your frontend should request a fresh token from your backend and retry.

Recreate pattern

async function getClient(walletAddress: string): Promise<BurnerClient> {
  const res = await fetch('/api/burn-session', {
    method: 'POST',
    body: JSON.stringify({ walletAddress }),
    headers: { 'Content-Type': 'application/json' },
  })
  const { token } = await res.json()
  return new BurnerClient({ sessionToken: token })
}

Session scopes

Scopes control what a session token is allowed to do. Request only the scopes your frontend needs.

If no scopes are specified, the session receives all four scopes by default.

Scope constants

The SDK exports a SessionScope enum for type-safe scope references:

import { SessionScope } from '@burnandclaim/sdk'
 
await server.createSession({
  walletAddress,
  scopes: [
    SessionScope.WalletRead,       // 'wallet:read'
    SessionScope.TransactionsBuild, // 'transactions:build'
    SessionScope.TransactionsSubmit, // 'transactions:submit'
  ],
})

Security best practices

1. Keep API keys on the server. Use environment variables, not hard-coded strings.
2. Request minimal scopes. If your frontend only needs to read assets, don’t request transactions:submit.
3. Use short TTLs. The default 5 minutes is usually enough. Only increase it if your UX flow takes longer.
4. Rotate API keys regularly. The dashboard lets you create multiple keys so you can rotate without downtime.
5. Bind tokens to wallets. Each session token is locked to the wallet address it was created for. A token for wallet A cannot access wallet B.