Authentication

Auth Type	Description	Register Auth Required	Use Case
API_Key	API key-based authentication	Yes	Server-to-server, automated systems
OAuth	OAuth 2.0 / OIDC authentication	Yes	Third-party identity providers
Email_Auth	Email-based OTP authentication	Yes	User email verification
SMS_Auth	SMS-based OTP authentication	Yes	Phone number verification
Passkey	WebAuthn passkey authentication	After any auth type	Secure device-based authentication

The Continuum system implements a two-tier authentication architecture:

Primary Authentication

Primary authentication methods must be registered first for any entity. These methods serve as the root authentication mechanism:

API Key - Cryptographic key-based authentication for server-to-server operations

OAuth - OpenID Connect (OIDC) authentication via third-party identity providers

Email Auth - Email-based OTP (One-Time Password) authentication

SMS Auth - SMS-based OTP authentication

Primary authentication is registered via the Register Auth endpoint

Secondary Authentication

Once primary authentication is established, entities may optionally register passkeys as a secondary authentication method for enhanced convenience:

Passkey - WebAuthn-based passkey authentication using biometric or device credentials.

Passkeys are registered via the Passkey Registration two-step process after primary authentication is in place.

Session Management for Primary Authentication

Primary authentication methods use different mechanisms to obtain signing credentials:

API Key Authentication (Permanent Keys) - For API Key authentication, the key pair registered during Register Auth serves as a permanent signing credential:

The registered private key is used directly to sign transaction payloads

No session creation required

Key pair remains valid until explicitly revoked

Suitable for server-to-server integrations and automated systems

Session-Based Authentication (Temporary Keys) - For OAuth, Email Auth, and SMS Auth, users must create a time-limited session to obtain temporary signing credentials. This process involves:

Step 1: Generate Ephemeral Key Pair

Generate a temporary ECDSA key pair using the P-256 (secp256r1) curve:

The public key must be in uncompressed format (65 bytes: 0x04 prefix + 32 bytes X coordinate + 32 bytes Y coordinate).

Step 2: Authentication-Specific Preparation

** For OAuth Authentication:**

Generate the SHA-256 hash of the ephemeral public key:

Obtain an OIDC token from your OAuth provider with the public key hash as the nonce claim

The nonce claim in the OIDC token must match the SHA-256 hash of the ephemeral public key provided in the session request.

For Email Auth / SMS Auth:

Call Initiate OTP to trigger OTP delivery:

POST /api/v1/wallets/{entityId}/initiate-otp

User receives OTP code via email or SMS

Use the OTP code in the session creation request

Step 3: Create Session

Call Start Session with the ephemeral public key and authentication credentials:

OAuth: Provide oidcToken (with public key hash as nonce)
Email/SMS: Provide otpId and otpCode

Step 4: Decrypt Credential Bundle

The response contains an encrypted credentialBundle:

Step 5: Sign Transactions

Use the session private key to sign transaction payloads:

Set signatureType: "ApiKey" in submit requests

Use the session private key to generate signatures

Session private key is valid for 15 minutes from creation

After expiration, create a new session to obtain fresh credentials

Session lifecycle

Generate Ephemeral Key Pair
  ↓
Authenticate (OAuth/OTP)
  ↓
Create Session → Receive credentialBundle
  ↓
Decrypt with Ephemeral Private Key
  ↓
Extract Session Private Key
  ↓
Sign Transactions (valid for 15 minutes)
  ↓
Session Expires → Create New Session

Payload Signing Rules

When performing operations that require payload signing (two-step processes), the following rules apply:

General Operations

For most two-step operations (wallet creation, account creation, transaction signing, etc.), payloads may be signed using either:

Primary Authentication - Using API Key-based signing (signatureType: "ApiKey")

For API Key auth: Use registered permanent key

For OAuth/Email/SMS auth: Use session private key from credential bundle

Secondary Authentication - Using Passkey/WebAuthn-based signing (signatureType: "WebAuthn")

This flexibility allows users to choose their preferred signing method based on context and convenience.

Passkey Management Operations

Authentication Flow Summary

Complete Flow for New Entity:

1. Register Primary Auth
   ↓
   POST /api/v1/wallets/{entityId}/register-auth
   ↓
   Entity created with API Key/OAuth/Email/SMS authentication

2. Create Session (OAuth/Email/SMS only)
   ↓
   a) Generate ephemeral P-256 key pair
   b) For OAuth: Get OIDC token with SHA256(publicKey) as nonce
      For Email/SMS: Call initiate-otp, receive OTP
   c) POST /api/v1/wallets/{entityId}/start-session
   d) Decrypt credentialBundle with ephemeral private key
   e) Extract session private key (valid 15 minutes)

   Note: API Key auth skips this step (uses registered key directly)

3. (Optional) Register Passkey
   ↓
   Signed with primary auth (session key or API key)
   ↓
   Passkey added as secondary auth method

4. Perform Operations
   ↓
   Sign with either:
   - Primary auth:
     * API Key: Use registered permanent key
     * OAuth/Email/SMS: Use session private key from credential bundle
   - Secondary auth: Use passkey (WebAuthn)

   Exception: Passkey management operations
   ↓
   Must sign with primary auth only

Session Renewal (OAuth/Email/SMS):

Session expired (after 15 minutes)
  ↓
Generate new ephemeral key pair
  ↓
Authenticate and create new session
  ↓
Decrypt new credential bundle
  ↓
Continue operations with new session key

Authentication

Session Management for Primary Authentication#

Session lifecycle#

Payload Signing Rules#

Authentication Flow Summary#

Session Management for Primary Authentication

Session lifecycle

Payload Signing Rules

Authentication Flow Summary