Entity Nanoid - Rise B2B API

Entity Nanoid is the primary identifier system used throughout the Rise B2B API for all entities and operations. Unlike RiseID (used for authentication), nanoids are used for API operations, database references, and internal entity management.

What is Nanoid?

A nanoid is a unique, URL-friendly identifier that follows a specific format: prefix + hyphen + 12-character random string. All nanoids in Rise are exactly 15 characters long and use a standardized prefix system to identify the entity type.

Nanoid Format

[prefix]-[12 random characters]

Example: te-abc123def456 (15 characters total)

Core Entity Nanoids

The primary entity types in Rise each have their own nanoid format:

Team Nanoid

Format: te-abc123def456
Example: te-xyz789abc123

Company Nanoid

Format: co-abc123def456
Example: co-def456ghi789

User Nanoid

Format: us-abc123def456
Example: us-ghi789jkl012

Complete Nanoid Reference

Here are all the nanoid types used in Rise B2B API:

Core Entities

Entity Type	Prefix	Format	Example	Description
Team	`te`	`te-abc123def456`	`te-xyz789abc123`	Team or department
Company	`co`	`co-abc123def456`	`co-def456ghi789`	Organization
User	`us`	`us-abc123def456`	`us-ghi789jkl012`	Individual user

Financial & Operational Entities

Entity Type	Prefix	Format	Example	Description
Payment	`pa`	`pa-abc123def456`	`pa-pay123def456`	Individual payment
Payment Group	`pg`	`pg-abc123def456`	`pg-grp123def456`	Batch payment group
Invite	`in`	`in-abc123def456`	`in-inv123def456`	User invitation

Nanoid Usage in API

Entity Balance API

The most common usage is in the entity balance endpoint:

curl -X GET "https://api.rise.works/v2/balance?nanoid=te-abc123def456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Team Management API

Team operations use team nanoids:

curl -X GET "https://api.rise.works/v2/teams/te-abc123def456/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Payments API

Payment operations use payment nanoids:

curl -X GET "https://api.rise.works/v2/payments?team_nanoid=te-abc123def456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Invites API

Invite management uses invite nanoids:

curl -X GET "https://api.rise.works/v2/invites?nanoid=te-abc123def456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Nanoid Validation

When working with nanoids, you should validate their format before making API calls:

Validation Rules

Length: Must be exactly 15 characters
Format: Must follow the pattern [prefix]-[12 random characters]
Prefix: Must start with a valid prefix (te-, co-, us-, pa-, pg-, in-)

Client-Side Validation

class NanoidValidator {
  // Validate nanoid format
  static validateNanoid(nanoid) {
    if (!nanoid || typeof nanoid !== 'string') {
      return false;
    }
    
    // Must be exactly 15 characters
    if (nanoid.length !== 15) {
      return false;
    }
    
    // Must have a valid prefix
    const validPrefixes = ['te-', 'co-', 'us-', 'pa-', 'pg-', 'in-'];
    return validPrefixes.some(prefix => nanoid.startsWith(prefix));
  }

  // Extract entity type from nanoid
  static getEntityType(nanoid) {
    if (nanoid.startsWith('te-')) return 'team';
    if (nanoid.startsWith('co-')) return 'company';
    if (nanoid.startsWith('us-')) return 'user';
    if (nanoid.startsWith('pa-')) return 'payment';
    if (nanoid.startsWith('pg-')) return 'payment_group';
    if (nanoid.startsWith('in-')) return 'invite';
    
    return 'unknown';
  }

  // Generate API URL based on nanoid type
  static getApiUrl(nanoid, endpoint) {
    const entityType = this.getEntityType(nanoid);
    
    switch (entityType) {
      case 'team':
        return `/v2/teams/${nanoid}${endpoint}`;
      case 'company':
        return `/v2/companies/${nanoid}${endpoint}`;
      case 'user':
        return `/v2/users/${nanoid}${endpoint}`;
      case 'payment':
        return `/v2/payments/${nanoid}${endpoint}`;
      case 'invite':
        return `/v2/invites/${nanoid}${endpoint}`;
      default:
        throw new Error(`Unsupported entity type: ${entityType}`);
    }
  }
}

interface NanoidInfo {
  entityType: string;
  prefix: string;
  randomPart: string;
  isValid: boolean;
}

class NanoidValidator {
  // Parse nanoid into components
  static parseNanoid(nanoid: string): NanoidInfo {
    if (!nanoid || typeof nanoid !== 'string') {
      return {
        entityType: 'unknown',
        prefix: '',
        randomPart: '',
        isValid: false
      };
    }

    const isValid = this.validateNanoid(nanoid);
    const prefix = nanoid.substring(0, 3); // Includes the hyphen
    const randomPart = nanoid.substring(3);
    const entityType = this.getEntityType(nanoid);

    return {
      entityType,
      prefix,
      randomPart,
      isValid
    };
  }

  // Validate nanoid format
  static validateNanoid(nanoid: string): boolean {
    if (!nanoid || typeof nanoid !== 'string') {
      return false;
    }
    
    // Must be exactly 15 characters
    if (nanoid.length !== 15) {
      return false;
    }
    
    // Must have a valid prefix
    const validPrefixes = ['te-', 'co-', 'us-', 'pa-', 'pg-', 'in-'];
    return validPrefixes.some(prefix => nanoid.startsWith(prefix));
  }

  // Extract entity type from nanoid
  static getEntityType(nanoid: string): string {
    if (nanoid.startsWith('te-')) return 'team';
    if (nanoid.startsWith('co-')) return 'company';
    if (nanoid.startsWith('us-')) return 'user';
    if (nanoid.startsWith('pa-')) return 'payment';
    if (nanoid.startsWith('pg-')) return 'payment_group';
    if (nanoid.startsWith('in-')) return 'invite';
    
    return 'unknown';
  }
}

Error Handling

Common errors when working with nanoids:

Error	Description	Solution
`Invalid nanoid format`	Nanoid doesn’t match expected pattern	Ensure nanoid is 15 characters with valid prefix
`Entity not found`	Nanoid doesn’t exist in system	Verify the nanoid exists and is correct
`Permission denied`	User lacks access to entity	Check user permissions for the entity
`Invalid entity type`	Nanoid type doesn’t match expected type	Verify you’re using the correct nanoid type

Common Error Scenarios

Invalid Nanoid Format:

{
  "success": false,
  "data": "Invalid nanoid format: must start with te-, co-, or us-"
}

Entity Not Found:

{
  "success": false,
  "data": "No entity found with nanoid te-invalid123"
}

Permission Denied:

{
  "success": false,
  "data": "User us-abc123def456 must have admin access to team te-xyz789abc123"
}

Best Practices

Validation

Always validate nanoid format before using

Documentation

Document which nanoid types your integration uses

Security

Never expose nanoid generation logic to clients

Caching

Cache nanoid lookups for performance

Security Considerations

Client-side validation: Always validate nanoid format before making API calls
No sequential patterns: Nanoids are cryptographically random
Prefix validation: Always validate the prefix matches expected entity type
Length validation: Ensure nanoids are exactly 15 characters

Performance Tips

Batch operations: Use batch endpoints when working with multiple nanoids
Caching: Cache frequently accessed nanoid lookups
Validation: Validate nanoid format early to avoid unnecessary API calls

RiseID

Understanding RiseID for authentication

Entity Balance

Balance management with nanoid

Teams

Team management concepts

Permissions

Understanding access control

Nanoid vs RiseID: Remember that nanoids are used for API operations and database references, while RiseID is used for authentication and smart contract interactions.

​What is Nanoid?

​Nanoid Format

​Core Entity Nanoids

Team Nanoid

Company Nanoid

User Nanoid

​Complete Nanoid Reference

​Core Entities

​Financial & Operational Entities

​Nanoid Usage in API

​Entity Balance API

​Team Management API

​Payments API

​Invites API

​Nanoid Validation

​Validation Rules

​Client-Side Validation

​Error Handling

​Common Error Scenarios

​Best Practices

Validation

Documentation

Security

Caching

​Security Considerations

​Performance Tips

​Related Concepts

RiseID

Entity Balance

Teams

Permissions

What is Nanoid?

Nanoid Format

Core Entity Nanoids

Complete Nanoid Reference

Core Entities

Financial & Operational Entities

Nanoid Usage in API

Entity Balance API

Team Management API

Payments API

Invites API

Nanoid Validation

Validation Rules

Client-Side Validation

Error Handling

Common Error Scenarios

Best Practices

Security Considerations

Performance Tips

Related Concepts