API User Onboarding Workflow

Overview

The Custody Engine uses a dual-key cryptographic authentication system for API users. This approach provides several security advantages over traditional authentication methods:

Why Cryptographic Authentication?

Key Benefits:

1. Non-repudiation: Every request is cryptographically signed, creating an audit trail that proves who initiated each action
2. No knowledge of private keys: The server never sees or stores private keys, eliminating credential theft from server breaches
3. End-to-end encryption: Request payloads are encrypted, protecting sensitive transaction data in transit
4. Device binding: Each device has unique credentials, enabling granular access control and revocation

The Dual-Key System

• ECDSA (P-256): Used for request signing and verification
• RSA (2048-bit): Used for payload encryption and decryption

Why two key types? Each algorithm is optimized for its specific purpose:

Each API user must generate both key pairs before registration. Upon successful creation, the server returns a device_uuid that uniquely identifies the user's authentication context. This UUID links the user's keys to their identity and must be included in all subsequent requests.

Onboarding Flow Diagram

What is COSE?

COSE (CBOR Object Signing and Encryption) is the message format used by the Custody Engine. It provides:

• Compact binary encoding: More efficient than JSON for cryptographic data
• Standardized structure: RFC 8152 compliant format
• Layered security: Supports both signing and encryption in a single envelope
• Interoperability: Used in WebAuthn, IoT, and other security-critical systems

The SDK handles all COSE encoding/decoding automatically - you work with regular JavaScript objects.

Prerequisites

Before onboarding an API user, ensure you have:

1. Admin-level access to create users
2. The @blockstream/ecs-js-sdk package installed
3. Access to the server's public keys (ECDSA and RSA)

Step-by-Step Onboarding Process

Step 1: Generate Cryptographic Key Pairs

The client must generate two key pairs before registration.

Important: Store the private keys securely. They cannot be recovered if lost.

Step 2: Create the API User

Any user with ability to invite new users can submit a user creation request with the generated public keys:

import { v4 as uuidv4 } from 'uuid'

const createPayload = await broadcastRequest({
  action: 'add',
  resource: '/users',
  details: {
    uid: uuidv4(),
    email: 'api_user@example.com',
    first_name: 'API',
    last_name: 'User',
    ecdsa_pubkey: userKeys.ecdsa.publicKeyHex,
    rsa_pubkey: userKeys.rsa.publicKeyPem,
    type: 'api',
  },
})

Request Parameters

Response

On success, the server returns:

const {
  uid, // The user's unique identifier
  device_uuid, // Device identifier for authentication
  server_ecdsa_pubkey, // Server's ECDSA public key (for verifying responses)
  server_rsa_pubkey, // Server's RSA public key (for encrypting requests)
} = createPayload.details

Step 3: Initialize the Blockstream SDK

With the keys and device UUID, initialize the SDK for authenticated requests:

import { Blockstream } from '@blockstream/ecs-js-sdk'

const userInstance = new Blockstream(
  userKeys.rsa.privateKeyPem, // User's RSA private key
  userKeys.ecdsa.privateKey, // User's ECDSA private key
  device_uuid, // Device UUID from creation response
  SERVER_RSA_PUBLIC_KEY_PEM, // Server's RSA public key
  SERVER_ECDSA_PUBLIC_KEY, // Server's ECDSA public key
)

SDK Constructor Parameters

Note: server keys are provided by the server during registration with invitation or in invitation response.

Step 4: Make Authenticated Requests

The SDK instance handles all cryptographic operations automatically:

const response = await broadcastRequest(
  {
    action: 'get',
    resource: `/users/${userId}`,
  },
  {},
  userInstance, // Pass the initialized SDK instance
)

[!NOTE]
broadcastRequest takes 3 parameters: request, options, and userInstance. request is an object with action, resource and details for the API request. options is an optional object for customizing the request to send unprotected request or configure COSE options. userInstance is the initialized SDK instance that handles authentication and signing.

All requests are:

• Signed with the user's ECDSA private key
• Encrypted with the server's RSA public key
• Wrapped in COSE (CBOR Object Signing and Encryption) format

Key Format Specifications

ECDSA Key Requirements

RSA Key Requirements

Device Management

Each API user can have multiple devices (key pairs). Use these endpoints to manage devices:

Key Rotation

TODO

Security Considerations

1. Private Key Storage: Never expose private keys in logs, version control, or client-side code. Use secure key management solutions.

2. Key Generation: Always generate keys using cryptographically secure random number generators.

3. Device Tracking: The server tracks last_access_at for each device, enabling audit trails and inactive device detection.

4. Password Protection: If a password is set during device authorization for non-api useres, all subsequent devices will require it for registration.

Example: Complete Onboarding Flow

import { Blockstream } from '@blockstream/ecs-js-sdk'
import { v4 as uuidv4 } from 'uuid'
import { generateUserKeyPairs } from './helpers/users'

async function onboardApiUser(email: string, firstName: string, lastName: string) {
  // 1. Generate key pairs
  const userKeys = await generateUserKeyPairs()

  // 2. Create the user (as admin)
  const createResponse = await broadcastRequest({
    action: 'add',
    resource: '/users',
    details: {
      uid: uuidv4(),
      email,
      first_name: firstName,
      last_name: lastName,
      ecdsa_pubkey: userKeys.ecdsa.publicKeyHex,
      rsa_pubkey: userKeys.rsa.publicKeyPem,
      type: 'api',
    },
  })

  if (createResponse.status !== 'success') {
    throw new Error(`User creation failed: ${createResponse.message}`)
  }

  const { device_uuid, uid } = createResponse.details

  // 3. Initialize SDK for the new user
  const userInstance = new Blockstream(
    userKeys.rsa.privateKeyPem,
    userKeys.ecdsa.privateKey,
    device_uuid,
    SERVER_RSA_PUBLIC_KEY_PEM,
    SERVER_ECDSA_PUBLIC_KEY,
  )

  // 4. Verify by fetching user profile
  const profileResponse = await broadcastRequest(
    { action: 'get', resource: `/users/${uid}` },
    {},
    userInstance,
  )

  return {
    userId: uid,
    deviceUuid: device_uuid,
    instance: userInstance,
    keys: {
      ecdsa: {
        privateKey: userKeys.ecdsa.privateKey,
        publicKeyHex: userKeys.ecdsa.publicKeyHex,
      },
      rsa: {
        privateKeyPem: userKeys.rsa.privateKeyPem,
        publicKeyPem: userKeys.rsa.publicKeyPem,
      },
    },
  }
}

Troubleshooting