Entity Nanoid

Understanding nanoid identifiers and their usage in the Rise ecosystem

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:

Request

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:

Request

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:

Request

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:

Request

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

1. Length: Must be exactly 15 characters
2. Format: Must follow the pattern [prefix]-[12 random characters]
3. 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}`);
    }
  }
}

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

Related Concepts

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.