User Classifications & UUID Identity Standard

Ternis Auth implements a role-based identity model designed for both open-source communities and commercial enterprise platforms. It standardizes on canonical RFC 4122 Version 4 UUIDs across all relational tables and APIs.

1. The Four User Classifications #

Every authenticated identity is categorized into one of four primary tiers:

                          ┌───────────────────────────┐
                          │   Authenticated User      │
                          └─────────────┬─────────────┘
                                        │
           ┌─────────────────┬──────────┴──────────┬─────────────────┐
           ▼                 ▼                     ▼                 ▼
   [ ternis_member ]  [ general_user ]    [ paying_customer ]    [ partner ]
   - Staff & Maintainers - Consumers      - Active Subscriber  - Verified B2B
   - Core Badges      - Community Forum   - SLA Support        - API Quotas
   - Internal Repos   - Standard Quotas   - Tier Plans         - App Self-Reg

Classification Breakdown #

1. Ternis Member (ternis_member) #

• Audience: Core engineering staff, foundation maintainers, and official open-source contributors.
• Entitlements:
  • Automatically granted ternis:member scope.
  • Organization badges and member indicators in UI applications.
  • Access to internal development resources, private repositories, and testing clusters.

2. General User (general_user) #

• Audience: Default registration tier for consumers, hobbyist developers, and community members.
• Entitlements:
  • Access to public ecosystem tools, account profile management, and standard community APIs.
  • Standard rate limits and public community support.

3. Paying Customer (paying_customer) #

• Audience: Commercial accounts and organizations with an active billing relationship.
• Subscription Plans:
  • starter: Basic commercial tier with elevated quotas.
  • pro: Professional tier with priority support and team seat management.
  • enterprise: Unlimited scalability, 99.99% SLA, and custom domain SSO.
• Entitlements:
  • Automatically granted ternis:customer scope.
  • Live subscription claims emitted in OpenID Connect UserInfo and tokens.

4. Verified Partner (partner) #

• Audience: Certified B2B software vendors, technology partners, and external app developers.
• Entitlements:
  • Automatically granted ternis:partner scope.
  • Elevated API rate limits (e.g. 5,000 req/min).
  • Self-service programmatic registration of confidential OAuth clients via POST /api/v1/oauth/clients.
  • Webhook delivery for ecosystem events.

2. Strict RFC 4122 Version 4 UUID Standard #

Ternis Auth strictly enforces RFC 4122 Version 4 UUIDs for all entity keys. Sequential integer IDs (1, 2, 3) are completely eliminated:

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
  │              │    │
  │              │    └── Variant: 8, 9, a, or b (RFC 4122)
  │              └─────── Version: 4 (Randomly Generated)
  └────────────────────── 128-bit Cryptographically Secure Integer

Affected Resources: #

• User IDs: users.id (e.g. b2f6b897-4001-460d-8386-db93f1d8c1c4)
• OAuth Client IDs: oauth_clients.id (e.g. 9dc6e84a-714c-4e89-9a29-bc828cf99874)
• Organization IDs: organizations.id
• Membership IDs: memberships.id
• Subscription IDs: customer_subscriptions.id
• Partner Profile IDs: partner_profiles.id
• SSO Audit Log IDs: sso_audit_logs.id

Why UUIDs? #

• Anti-Enumeration: Malicious actors cannot scrape user profiles or infer total user count by incrementing numbers.
• Distributed Generation: Microservices and client applications can safely generate unique IDs without database roundtrips.
• Safe Cross-Domain Merges: Prevents primary key collisions when synchronizing databases.

3. Organizations & Memberships #

Users can belong to multiple organizations or teams with specific roles:

• owner: Full control over billing, memberships, and organizational credentials.
• admin: Manages team members, OAuth applications, and access policies.
• member: Standard collaborator with access to organizational resources.
• viewer: Read-only access to organizational analytics and services.

Querying Memberships via API #

Authenticated requests to GET /api/v1/memberships return an array of user affiliations:

{
  "user_id": "b2f6b897-4001-460d-8386-db93f1d8c1c4",
  "memberships": [
    {
      "organization_id": "c8a7f920-5d61-41b3-a1f4-3d078be12884",
      "organization_name": "Ternis Core Platform",
      "slug": "ternis-core",
      "role": "admin",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}