Add Organization Service Accounts and Service Tokens #76
Description
🚀 Feature Description
Introduce Organization Service Accounts and Service Tokens to allow external systems (CI/CD, automation tools, integrations) to interact with the Tron Platform using scoped, non-user credentials that fully integrate with the existing RBAC and permission model.
Service tokens will represent a service account within an organization, inheriting permissions exclusively through group membership (same as users).
💡 Motivation
Currently, all API access is performed using user tokens, which tightly couples automation and integrations to individual users. This creates several issues:
- Security risks when using long-lived user tokens in CI/CD pipelines
- Lack of clear ownership and auditability for automated actions
- Difficulty enforcing least-privilege access for integrations
- Poor token rotation and revocation experience
A dedicated service token mechanism is required to support automation safely and cleanly.
🎯 Proposed Solution
Implement Organization Service Accounts and Service Tokens with the following principles:
- A service account is a first-class principal inside an organization
- Service accounts participate in the same RBAC model as users via groups
- Service tokens authenticate requests and resolve to a service account
- Permissions are derived only from group membership, not token-level roles
High-level behavior:
- Org admins create service accounts
- Org admins generate service tokens (shown only once)
- Service accounts are added to existing groups (ORG / ENV / APP scopes)
- API authorization reuses
OrganizationAccessContext
🔄 Alternatives Considered
1. Token-level roles or scopes
- Rejected due to duplication of authorization logic
- Would introduce a parallel permission system
2. Synthetic “system users”
- Rejected due to poor auditability
- Blurs the distinction between human users and automation
3. Global service tokens
- Rejected due to security risks and lack of organization isolation
📋 Additional Context
- Service tokens should be organization-scoped
- Tokens must be stored hashed (never plaintext)
- Tokens should support:
- Expiration dates
- Revocation
- Usage tracking (
last_used_at)
- Tokens should never have implicit “admin” or “superuser” privileges
This feature is critical to support:
- CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
- Terraform / IaC automation
- External platform integrations
- Future API-first use cases
🎨 UI/UX Considerations
Affected screens:
- Organization details page
- New “Service Accounts” section under Organization
User interactions:
- Create / edit / disable service accounts
- Generate service tokens (token visible only once)
- Assign service accounts to groups
- Revoke and rotate tokens
UX principles:
- Clear distinction between Users and Service Accounts
- Clear warning when generating tokens (one-time visibility)
- Visibility into token usage (last used, expiration)
No UI mockups yet — can be designed after backend contract is defined.
🔧 Technical Considerations
API Changes
- Authentication layer must support:
- User tokens
- Service tokens (opaque tokens stored hashed)
- Authorization flow must:
- Resolve service token → service account → organization member → groups
- Reuse existing permission checks (
OrganizationAccessContext)
Database Schema
- New tables:
organization_service_accountsorganization_service_tokens
- Extend
organization_membersto support:principal_type = user | service_account- Nullable
service_account_id
Security
- Token hashing (e.g. HMAC or bcrypt)
- Optional expiration (
expires_at) - Revocation support
- Rate limiting for service tokens
Performance
- Token resolution should be cached where possible
- No significant performance impact expected if authorization context reuse is preserved