Authentication

Authentication Methods

The Bloque SDK supports two authentication methods depending on your platform:

API Key - For backend environments (Node.js, Bun, Deno)
JWT - For frontend environments (browsers, React Native)

The SDK automatically validates that your authentication method matches your platform.

API Key Authentication

API key authentication is used for server-side applications where you can securely store credentials.

When to Use API Keys

Use API key authentication when:

Running in Node.js, Bun, or Deno
Building backend services or APIs
You can securely store the API key (never in client-side code)
You need full programmatic control over user sessions

Setup

Get Your Credentials

You’ll need:

Origin: Your organization identifier
API Key: Your secret authentication key

Store these securely in environment variables:

.env

BLOQUE_ORIGIN=your-origin
BLOQUE_API_KEY=your-api-key
BLOQUE_MODE=production  # or 'sandbox'

Initialize the SDK

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: process.env.BLOQUE_ORIGIN!,
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
  platform: 'node', // or 'bun', 'deno'
});

With API key auth, you can register new users or connect to existing ones:

// Register a new user
const session = await bloque.register('@alice', {
  type: 'individual',
  profile: {
    firstName: 'Alice',
    lastName: 'Smith',
    email: '[email protected]',
    phone: '+1234567890',
    birthdate: '1992-05-15',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    countryOfBirthCode: 'US',
    countryOfResidenceCode: 'US',
  },
});

// Or connect to an existing user
const session = await bloque.connect('@alice');

console.log('Connected to:', session.urn);

Session Object

The register() and connect() methods return a session object with access to all APIs:

const session = await bloque.connect('@alice');

// Access user resources
session.accounts   // Accounts API (cards, virtual, polygon, etc.)
session.compliance // Compliance API (KYC/KYB)
session.identity   // Identity API (aliases, profile)
session.orgs       // Organizations API
session.swap       // Swap API (currency exchange)
session.urn        // User's unique resource name
session.accessToken // Current access token (read-only)

Complete Example

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: process.env.BLOQUE_ORIGIN!,
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
});

// Connect to user
const session = await bloque.connect('@alice');

// Create a virtual account
const virtual = await session.accounts.virtual.create({});

// Create a card
const card = await session.accounts.card.create({
  ledgerId: virtual.ledgerId,
  name: 'Alice\'s Card',
});

console.log('Card created:', card.urn);

Never expose your API key in client-side code, version control, or public repositories.

JWT Authentication

JWT (JSON Web Token) authentication is used for client-side applications where API keys cannot be securely stored.

When to Use JWT

Use JWT authentication when:

Running in browsers or React Native
Building frontend applications
Users authenticate directly with the platform
You cannot securely store API keys

Browser Setup

Initialize with JWT

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  auth: {
    type: 'jwt',
  },
  mode: 'production',
  platform: 'browser',
});

For browser platforms, the SDK uses credentials: 'include' to support httpOnly cookies.

Authenticate

// Authenticate and get user session
const session = await bloque.authenticate();

console.log('Authenticated as:', session.urn);

Two-Factor Authentication (OTP)

For operations requiring additional verification:

// Request OTP
const result = await bloque.assert('your-origin', '[email protected]');

console.log('OTP sent to:', result.value.email);
console.log('Expires at:', result.value.expires_at);

// Verify OTP and connect
const session = await bloque.connect(
  'your-origin',
  '[email protected]',
  '123456' // OTP code
);

React Native Setup

Install Dependencies

npm install @bloque/sdk
npm install @react-native-async-storage/async-storage

Implement Token Storage

import AsyncStorage from '@react-native-async-storage/async-storage';

const tokenStorage = {
  get: async () => {
    return await AsyncStorage.getItem('bloque_token');
  },
  set: async (token: string) => {
    await AsyncStorage.setItem('bloque_token', token);
  },
  clear: async () => {
    await AsyncStorage.removeItem('bloque_token');
  },
};

Initialize SDK

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  auth: {
    type: 'jwt',
  },
  mode: 'production',
  platform: 'react-native',
  tokenStorage,
});

Secure Token Storage

For production applications, use secure storage mechanisms:

// Recommended: Use httpOnly cookies set by your backend
const tokenStorage = {
  get: () => null, // Token sent automatically in cookies
  set: (token) => {
    // Send to backend to set httpOnly cookie
    fetch('/api/auth/set-token', {
      method: 'POST',
      body: JSON.stringify({ token }),
    });
  },
  clear: () => {
    fetch('/api/auth/logout', { method: 'POST' });
  },
};

Security Warning: localStorage and sessionStorage are vulnerable to XSS attacks. Use httpOnly cookies (browser) or secure storage (React Native) for production applications.

Configuration Options

Both authentication methods support additional configuration:

const bloque = new SDK({
  origin: 'your-origin',
  auth: { type: 'apiKey', apiKey: 'your-key' },
  mode: 'production', // or 'sandbox'
  platform: 'node', // 'node' | 'bun' | 'deno' | 'browser' | 'react-native'
  
  // Optional: Custom base URL
  baseUrl: 'https://custom-api.bloque.app',
  
  // Optional: Request timeout (default: 30000ms)
  timeout: 30000,
  
  // Optional: Retry configuration
  retry: {
    enabled: true,
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 30000,
  },
});

Error Handling

Handle authentication errors gracefully:

import { SDK } from '@bloque/sdk';
import { BloqueAuthenticationError } from '@bloque/sdk-core';

try {
  const bloque = new SDK({
    origin: process.env.BLOQUE_ORIGIN!,
    auth: {
      type: 'apiKey',
      apiKey: process.env.BLOQUE_API_KEY!,
    },
  });

  const session = await bloque.connect('@alice');
} catch (error) {
  if (error instanceof BloqueAuthenticationError) {
    console.error('Authentication failed:', error.message);
    console.error('Request ID:', error.requestId);
  } else {
    console.error('Unexpected error:', error);
  }
}

Best Practices

Backend: Use API Keys

Always use API key authentication for server-side applications.

Frontend: Use JWT

Use JWT authentication for client-side applications.

Never Expose Secrets

Never commit API keys to version control or expose them in client code.

Use Environment Variables

Store credentials in environment variables, not in source code.

Rotate Keys Regularly

Rotate API keys periodically for better security.

Use Sandbox for Testing

Always test with sandbox mode before going to production.

Next Steps

Quickstart

Get started with your first API call

API Reference

Explore the complete API documentation

Error Handling

Learn about error types and handling

Guides

Browse practical guides and examples

Get Started

Core Concepts

Accounts

Swap & Exchange

Identity & Compliance

Organizations

Guides

Authentication Methods

API Key Authentication

When to Use API Keys

Setup

Session Object

Complete Example

JWT Authentication

When to Use JWT

Browser Setup

React Native Setup

Secure Token Storage

Configuration Options

Error Handling

Best Practices

Backend: Use API Keys

Frontend: Use JWT

Never Expose Secrets

Use Environment Variables

Rotate Keys Regularly

Use Sandbox for Testing

Next Steps

Quickstart

API Reference

Error Handling

Guides

Build docs developers (and LLMs) love

Get Started

Core Concepts

Accounts

Swap & Exchange

Identity & Compliance

Organizations

Guides

​Authentication Methods

​API Key Authentication

​When to Use API Keys

​Setup

​Session Object

​Complete Example

​JWT Authentication

​When to Use JWT

​Browser Setup

​React Native Setup

​Secure Token Storage

​Configuration Options

​Error Handling

​Best Practices

Backend: Use API Keys

Frontend: Use JWT

Never Expose Secrets

Use Environment Variables

Rotate Keys Regularly

Use Sandbox for Testing

​Next Steps

Quickstart

API Reference

Error Handling

Guides

Build docs developers (and LLMs) love

Authentication Methods

API Key Authentication

When to Use API Keys

Setup

Session Object

Complete Example

JWT Authentication

When to Use JWT

Browser Setup

React Native Setup

Secure Token Storage

Configuration Options

Error Handling

Best Practices

Next Steps