Skip to main content

​
Overview

The Identity module provides a comprehensive system for managing user identities across multiple origins (authentication providers). It supports both individual users (KYC) and business entities (KYB), with features for alias management and multi-origin registration.

​
Key Concepts

​
Identity URN

Every identity in the Bloque platform is uniquely identified by a URN (Uniform Resource Name) in the format: 
did:bloque:origin:{namespace}:{alias}

​
Origins

Origins represent authentication providers or entry points for identities. Common origin types include:
  • EVM Blockchains - Ethereum, Polygon, Base, etc. (using wallet signatures)
  • OAuth Providers - Auth0 and other OAuth2 providers
  • OTP Providers - WhatsApp, Email
  • API Keys - Traditional API key authentication

​
Aliases

Aliases are human-readable identifiers associated with an identity. Examples:
  • Email addresses: [email protected]
  • Phone numbers: +1234567890
  • Blockchain addresses: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6

​
Identity Client

The IdentityClient provides access to identity management functionality: 
import { SDK } from '@bloque/sdk';

const bloque = SDK.connect({
  apiKey: 'your-api-key',
  environment: 'sandbox'
});

// Access identity services
const identity = bloque.identity;

​
Get Current Identity

Retrieve the authenticated user’s identity profile: 
const me = await bloque.identity.me();

console.log(me.urn);      // Identity URN
console.log(me.origin);   // Origin namespace
console.log(me.type);     // 'individual' or 'business'
console.log(me.status);   // Identity status
console.log(me.profile);  // Profile information

​
Identity Profile Types

​
Individual Profile

identity/src/types.ts
interface IdentityMeProfile {
  city: string;
  email: string;
  phone: string;
  state: string;
  gender: string;
  birthdate: string;              // ISO 8601 format (YYYY-MM-DD)
  last_name: string;
  first_name: string;
  postal_code: string;
  neighborhood: string;
  address_line1: string;
  address_line2?: string;
  personal_id_type: string;       // e.g., 'SSN', 'passport'
  personal_id_number: string;
  country_of_birth_code: string;  // ISO country code
  country_of_residence_code: string;
}

​
Identity Response

identity/src/types.ts
interface IdentityMe {
  urn: string;                    // Unique identity URN
  origin: string;                 // Origin namespace
  type: string;                   // 'individual' or 'business'
  profile: IdentityMeProfile;     // Profile data
  status: string;                 // Identity status
  metadata: Record<string, unknown>;
}

​
Sub-Modules

The Identity module includes specialized sub-clients:

Aliases

Manage identity aliases and lookups

Origins

Register identities and manage origins

​
Example: Complete Identity Flow

// 1. List available origins
const origins = await bloque.identity.origins.list();
console.log('Available origins:', origins);

// 2. Register a new identity (see Origins documentation)
const registration = await bloque.identity.origins.register(
  'ethereum-mainnet',
  registerParams
);

// 3. Get identity information
const me = await bloque.identity.me();

// 4. Look up an alias
const alias = await bloque.identity.aliases.get('[email protected]');

​
Status Values

Identities can have the following statuses:
  • active - Identity is active and can perform operations
  • inactive - Identity is temporarily inactive
  • awaiting_compliance_verification - Pending KYC/KYB verification
  • suspended - Identity has been suspended

​
Best Practices

Choose the origin type that matches your use case:
  • Blockchain apps: Use EVM or other chain-specific origins
  • Web apps: Use OAuth or email/WhatsApp OTP
  • Backend services: Use API key authentication
Users may have multiple aliases across different origins. Use the URN as the canonical identifier.
Always check the identity status before performing sensitive operations.

Compliance

KYC/KYB verification for identities

Organizations

Manage business organizations

Build docs developers (and LLMs) love

Get started for freeTalk to us