Skip to main content
Bloque uses URNs (Uniform Resource Names) as a standardized way to identify identities and resources across the platform. URNs provide a consistent, globally unique identifier format.

​
URN Format

Bloque URNs follow the Decentralized Identifier (DID) specification: 
did:bloque:{origin}:{alias}
​
did
string
DID method prefix (always "did")
​
bloque
string
DID method name (always "bloque")
​
origin
string
Origin identifier that scopes the identity to your application or organization
​
alias
string
Unique identifier for the user within the origin (email, phone, username, etc.)

​
URN Examples

Examples
// Email-based identity
"did:bloque:my-app:[email protected]"

// Phone-based identity
"did:bloque:my-app:+1234567890"

// Username-based identity
"did:bloque:my-app:johndoe"

// Custom identifier
"did:bloque:my-app:customer-12345"

​
URN Construction

The SDK automatically constructs URNs when you register or connect to an identity. You can also access the URN building logic:
Automatic URN Construction
import { SDK } from '@bloque/sdk';

const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app'
});

// Register a new identity - URN is constructed automatically
const session = await sdk.register('[email protected]', {
  firstName: 'John',
  lastName: 'Doe'
});

// Access the URN
console.log(session.urn);
// Output: "did:bloque:my-app:[email protected]"
The URN construction happens in the SDK’s buildUrn method:
packages/sdk/src/bloque.ts:40-47
private buildUrn(alias: string): string {
  const origin = this.httpClient.origin;
  if (!origin) {
    throw new Error('Origin is required to build a urn');
  }

  return `did:bloque:${origin}:${alias}`;
}

​
Accessing URNs

After successfully authenticating, the URN is available through the session object: 
const session = await sdk.connect('[email protected]');

// Access the URN
const userUrn = session.urn;
console.log(userUrn); // "did:bloque:my-app:[email protected]"

// Use URN for resource operations
const account = await session.accounts.virtual.create({
  currency: 'USD'
});

​
URN Scoping

​
Origin-Based Scoping

URNs are scoped to an origin, which represents your application or organization. This ensures identities are isolated between different applications: 
const sdk1 = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_app1_...' },
  origin: 'app-1'
});

const session1 = await sdk1.connect('[email protected]');
console.log(session1.urn);
// "did:bloque:app-1:[email protected]"
These are two different identities even though they use the same alias. The origin provides isolation.

​
Alias Uniqueness

Aliases must be unique within an origin. Attempting to register a duplicate alias will result in a validation error: 
const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app'
});

// First registration succeeds
await sdk.register('[email protected]', {
  firstName: 'John',
  lastName: 'Doe'
});

// Second registration with same alias fails
try {
  await sdk.register('[email protected]', {
    firstName: 'Jane',
    lastName: 'Smith'
  });
} catch (error) {
  // BloqueValidationError: Alias already exists
}

​
URN Usage Patterns

​
Identity Lookup

Use URNs to look up and reference identities: 
// Get identity information
const identity = await session.identity.get('did:bloque:my-app:[email protected]');

console.log(identity.urn);        // "did:bloque:my-app:[email protected]"
console.log(identity.firstName);  // "John"
console.log(identity.lastName);   // "Doe"

​
Resource Association

Resources (like accounts) are automatically associated with the authenticated identity’s URN: 
const session = await sdk.connect('[email protected]');
// session.urn = "did:bloque:my-app:[email protected]"

// Create account - automatically associated with the URN
const account = await session.accounts.virtual.create({
  currency: 'USD'
});

// Account is owned by the identity with this URN
console.log(account.holderUrn); // "did:bloque:my-app:[email protected]"

​
Multi-Origin Identity

The same person can have different URNs across different origins:
Multi-App Scenario
// User in mobile app
const mobileSession = await mobileSdk.connect('[email protected]');
// URN: "did:bloque:mobile-app:[email protected]"

// Same user in web app
const webSession = await webSdk.connect('[email protected]');
// URN: "did:bloque:web-app:[email protected]"

// These are separate identities with separate data

​
URN Validation

When working with URNs manually, ensure they follow the correct format: 
function isValidBloqueUrn(urn: string): boolean {
  // Basic URN format validation
  const urnPattern = /^did:bloque:[a-zA-Z0-9-_]+:.+$/;
  return urnPattern.test(urn);
}

// Valid URNs
console.log(isValidBloqueUrn('did:bloque:my-app:[email protected]')); // true
console.log(isValidBloqueUrn('did:bloque:prod:+1234567890'));        // true

// Invalid URNs
console.log(isValidBloqueUrn('bloque:my-app:user'));                 // false
console.log(isValidBloqueUrn('did:other:my-app:user'));              // false

​
URN Best Practices

Use Stable Aliases

Choose aliases that won’t change (email, phone, user ID) rather than temporary values

Origin Naming

Use descriptive, kebab-case origin names (e.g., my-mobile-app, production-api)

Don't Parse URNs

Use the SDK’s URN property rather than parsing URN strings manually

Store URNs

Store the complete URN in your database for future reference and lookups

​
JWT Authentication URN Resolution

When using JWT authentication, the URN is resolved during the authenticate() or connect() flow: 
const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'jwt' }
  // origin not required - will be resolved
});

// Authenticate with existing JWT
const session = await sdk.authenticate();

// Origin and URN are resolved from the JWT
console.log(session.urn);    // "did:bloque:resolved-origin:[email protected]"

​
URN in API Responses

Many API responses include URN fields for identity references: 
const identity = await session.identity.me();

console.log(identity);
// {
//   urn: "did:bloque:my-app:[email protected]",
//   origin: "my-app",
//   aliases: ["[email protected]"],
//   firstName: "John",
//   lastName: "Doe",
//   ...
// }

Configuration

Learn about the origin configuration option

Authentication

Register and connect identities

Identity API

Manage identities and aliases

Build docs developers (and LLMs) love

Get started for freeTalk to us