Skip to main content

​
Overview

Aliases are human-readable identifiers associated with identities in the Bloque platform. They serve as convenient references to user accounts and can be used for lookups, transfers, and identity verification.

​
What is an Alias?

An alias can be any unique identifier associated with an identity:
  • Email addresses: [email protected]
  • Phone numbers: +1234567890
  • Blockchain addresses: 0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6
  • Custom identifiers: Application-specific usernames or IDs

​
Alias Structure

Each alias contains detailed information about the identity it represents:
identity/src/internal/wire-types.ts
type AliasResponse = {
  id: string;                           // Unique alias ID
  alias: string;                        // The alias value
  type: 'phone' | 'email' | string;     // Alias type
  urn: string;                          // Associated identity URN
  origin: string;                       // Origin namespace
  details: {
    phone?: string;                     // Phone number (for phone aliases)
  };
  metadata: {
    alias: string;
    [key: string]: unknown;
  };
  status: 'active' | 'inactive' | 'revoked';
  is_public: boolean;                   // Whether alias is publicly visible
  is_primary: boolean;                  // Whether this is the primary alias
  created_at: string;                   // ISO 8601 timestamp
  updated_at: string;                   // ISO 8601 timestamp
}

​
Get Alias Information

Look up detailed information about an alias: 
const alias = await bloque.identity.aliases.get('[email protected]');

console.log(alias.urn);        // Identity URN
console.log(alias.origin);     // Origin namespace
console.log(alias.type);       // 'email'
console.log(alias.status);     // 'active'
console.log(alias.is_primary); // true

​
Example: Email Alias Lookup

const emailAlias = await bloque.identity.aliases.get('[email protected]');

if (emailAlias.status === 'active') {
  console.log('User URN:', emailAlias.urn);
  console.log('Origin:', emailAlias.origin);
  console.log('Primary alias:', emailAlias.is_primary);
}

​
Example: Phone Number Lookup

const phoneAlias = await bloque.identity.aliases.get('+1234567890');

console.log('Phone:', phoneAlias.details.phone);
console.log('User URN:', phoneAlias.urn);

​
Example: Blockchain Address Lookup

const walletAlias = await bloque.identity.aliases.get(
  '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6'
);

console.log('Wallet address verified');
console.log('Associated identity:', walletAlias.urn);
console.log('Origin:', walletAlias.origin); // e.g., 'ethereum-mainnet'

​
Alias Status

Aliases can have different statuses:
StatusDescription
activeAlias is active and can be used
inactiveAlias is temporarily inactive
revokedAlias has been permanently revoked

​
Primary vs Secondary Aliases

Each identity can have multiple aliases, but only one can be marked as primary: 
const alias = await bloque.identity.aliases.get('[email protected]');

if (alias.is_primary) {
  console.log('This is the primary alias for the identity');
}

​
Public vs Private Aliases

Aliases can be public or private:
  • Public aliases (is_public: true) - Visible in public directories and lookups
  • Private aliases (is_public: false) - Only visible to the identity owner and authorized parties
const alias = await bloque.identity.aliases.get('[email protected]');

if (alias.is_public) {
  console.log('This alias is publicly discoverable');
}

​
Use Cases

Before sending payments, look up the recipient’s alias to verify their identity:
const recipient = await bloque.identity.aliases.get('[email protected]');

if (recipient.status === 'active') {
  // Proceed with payment using recipient.urn
  await bloque.accounts.virtual.transfer({
    fromAccountUrn: senderAccount,
    toHolderUrn: recipient.urn,
    amount: '100.00',
    currency: 'USD'
  });
}
Verify a user’s alias during registration or authentication:
const alias = await bloque.identity.aliases.get(userEmail);

if (alias.status === 'active' && alias.origin === 'bloque-email') {
  console.log('Email verified and active');
}
Check if a blockchain address is associated with a Bloque identity:
const walletAlias = await bloque.identity.aliases.get(walletAddress);

console.log('Wallet origin:', walletAlias.origin);
console.log('Identity URN:', walletAlias.urn);

​
Error Handling

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

try {
  const alias = await bloque.identity.aliases.get('[email protected]');
} catch (error) {
  if (error instanceof BloqueNotFoundError) {
    console.log('Alias not found');
  }
}

​
Best Practices

Always validate alias status before using it for critical operations like payments or access control.
Use the URN (from alias.urn) as the canonical identifier for identities, not the alias itself. Aliases can change, but URNs are permanent.
Alias lookups are case-sensitive for most types. Normalize email addresses and other identifiers before lookup.

Origins

Register identities and manage origins

Identity Overview

Learn about identity management

Build docs developers (and LLMs) love

Get started for freeTalk to us