Security

Teams & Roles

Role-based access control for AxiomDB projects with granular permissions for owners, admins, developers, viewers, and billing users.

Teams & Roles

AxiomDB implements role-based access control (RBAC) at the project level. Every member of a project is assigned a single role that determines what actions they can perform. Sensitive actions are additionally gated by confirmation flows and audit logging.

Role Hierarchy

Roles are ordered from most to least privileged. Higher roles inherit all permissions of lower roles unless explicitly overridden.

┌──────────────────────────────────────────────────────┐
│                     OWNER                            │
│  • Everything below                                 │
│  • Delete project                                   │
│  • Enable public network modes                      │
│  • Manage billing                                   │
│  • Transfer ownership                               │
│  • Remove any member                                │
├──────────────────────────────────────────────────────┤
│                     ADMIN                            │
│  • Everything below                                 │
│  • Create/delete branches                           │
│  • Manage network rules                             │
│  • Initiate restores                                │
│  • Rotate credentials                               │
│  • View credentials (if policy allows)              │
├──────────────────────────────────────────────────────┤
│                    DEVELOPER                         │
│  • Everything below                                 │
│  • Create branches                                  │
│  • View credentials (if policy allows)              │
│  • Run queries                                      │
│  • View branch metadata                             │
├──────────────────────────────────────────────────────┤
│                     VIEWER                           │
│  • Read-only dashboard access                       │
│  • View branch list                                 │
│  • View network rules (no modification)             │
│  • View audit log                                   │
├──────────────────────────────────────────────────────┤
│                    BILLING                           │
│  • Manage payment methods                           │
│  • View invoices                                    │
│  • Update subscription                              │
│  • No database or infrastructure access             │
└──────────────────────────────────────────────────────┘

Permission Matrix

ActionOwnerAdminDeveloperViewerBilling
View dashboard✅✅✅✅✅
View branch list✅✅✅✅❌
View network rules✅✅✅✅❌
View audit log✅✅✅✅❌
Run queries✅✅✅❌❌
Create branches✅✅✅❌❌
View credentials✅✅⚠️❌❌
Rotate credentials✅✅❌❌❌
Manage network rules✅✅❌❌❌
Delete branches✅✅❌❌❌
Initiate restore✅✅❌❌❌
Enable public mode✅❌❌❌❌
Delete project✅❌❌❌❌
Manage billing✅❌❌❌✅
Invite members✅✅❌❌❌
Remove members✅⚠️❌❌❌
Change member roles✅⚠️❌❌❌

Developer credential access

Developers can only view credentials if the project policy allow_developer_credential_access is set to true. This defaults to false and can only be changed by an owner.

Admin limitations

Admins cannot remove owners or promote anyone to owner. Admins can remove developers, viewers, and billing users, but not other admins. Only owners can remove admins.

Sensitive Actions

The following actions require additional verification beyond role checks. Each action triggers an audit event and may require explicit confirmation.

ActionMinimum RoleConfirmationAudit Event
Reveal credentialsDeveloper*Nonebranch.credentials.viewed
Rotate credentialsAdminNonebranch.credentials.rotated
Enable public runtime modeOwnerNonenetwork.policy.changed
Enable public all modeOwnerType project namenetwork.policy.changed
Delete branchAdminType branch namebranch.deleted
Delete projectOwnerType project nameproject.deleted
Restore backupAdminNonebackup.restore.started
Invite memberAdminNoneteam.invitation.created
Remove memberAdminNoneteam.member.removed
Change roleAdminNoneteam.member.role_changed

Inviting Members

Via Dashboard

  1. Navigate to Project Settings → Team.
  2. Click Invite Member.
  3. Enter the email address and select a role.
  4. The invitee receives an email with a secure link.
  5. The invitation expires after 7 days.

Via CLI

axiom team invite \
  --project my-project \
  --email "alice@example.com" \
  --role developer

Via API

curl -X POST "https://api.axiom.cloud/v1/projects/prj_abc123/team/invitations" \
  -H "Authorization: Bearer ptk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "developer"
  }'

Response:

{
  "id": "inv_7xK2mP9n",
  "email": "alice@example.com",
  "role": "developer",
  "status": "pending",
  "expires_at": "2026-01-22T10:30:00Z",
  "created_at": "2026-01-15T10:30:00Z",
  "invited_by": "usr_8xK2mP"
}

Changing Roles

Role changes take effect immediately. The member's existing connections are not terminated, but all subsequent API calls are authorized against the new role.

axiom team role update \
  --project my-project \
  --member usr_alice123 \
  --role admin

Downgrade impact

Downgrading a member from admin to developer immediately revokes access to network management, credential rotation, branch deletion, and restore operations. Active sessions will see permission errors on next API call.

Removing Members

Removing a member revokes all access immediately. Active database connections are terminated after a 60-second grace period to allow in-flight queries to complete.

axiom team remove \
  --project my-project \
  --member usr_alice123

The removed member receives a notification email. All their API tokens for this project are invalidated.

Role-Specific Behavior

Owner

The owner role is singular in its capabilities:

  • Network mode escalation: Only owners can switch from restricted to public_runtime or public_all. The public_all mode requires typing the project name verbatim.
  • Project deletion: Irreversible. Requires typing the project name. All data, branches, backups, and team memberships are destroyed.
  • Billing: Full access to payment methods, invoices, and subscription management.
  • Ownership transfer: Can transfer ownership to another member. The previous owner becomes an admin.

Admin

Admins handle day-to-day operations:

  • Branch lifecycle: Create, delete, and manage branches.
  • Network rules: Add, modify, and remove CIDR rules.
  • Credential rotation: Rotate runtime, direct, or both credential sets.
  • Restore: Initiate point-in-time restores from backups.
  • Team management: Invite members and manage roles up to admin level.

Developer

Developers focus on building:

  • Branch creation: Can create branches (if the project allows developer-created branches).
  • Query execution: Full query access via the dashboard and connected clients.
  • Credential access: Conditional on allow_developer_credential_access policy.
  • Read access: Can view branches, network rules, and audit logs.

Viewer

Viewers have read-only access:

  • Dashboard: View project overview, branch list, and metrics.
  • Audit log: View but not export.
  • No write operations: Cannot create branches, run queries, or modify any configuration.

Billing

The billing role is purpose-built for finance teams:

  • Payment methods: Add, update, and remove credit cards.
  • Invoices: View and download invoices.
  • Subscription: Upgrade, downgrade, or cancel.
  • No technical access: Cannot view branches, databases, or credentials.

API Token Scopes

API tokens can be scoped to a specific role. The token cannot exceed the permissions of the role assigned to it.

{
  "token_id": "ptk_xxxxxxxxxxxx",
  "name": "CI Deploy Token",
  "role": "developer",
  "scopes": ["branches:read", "branches:create", "credentials:read"],
  "expires_at": "2026-06-01T00:00:00Z",
  "rate_limit": 1000,
  "created_at": "2025-01-15T10:30:00Z"
}

Token scopes reference

ScopeDescriptionMinimum Role
branches:readList and view branch metadataViewer
branches:createCreate new branchesDeveloper
branches:deleteDelete branchesAdmin
credentials:readView connection credentialsDeveloper*
credentials:rotateRotate credentialsAdmin
network:readView network rulesViewer
network:writeCreate, update, delete network rulesAdmin
audit:readView audit logViewer
team:readView team membersViewer
team:writeInvite, remove, and change rolesAdmin
billing:readView invoices and payment methodsBilling
billing:writeManage billingBilling

Authentication Flow

AxiomDB supports two authentication methods:

PASETO v4 Tokens

All API tokens are PASETO v4 tokens signed with Ed25519 keys. Tokens are generated server-side and displayed once at creation. They cannot be retrieved later.

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│  Client   │────▶│  API Gateway │────▶│ Token Verify │
│  (Bearer) │     │              │     │  (Ed25519)   │
└──────────┘     └──────┬───────┘     └──────┬───────┘
                        │                     │
                        ▼                     ▼
                 ┌──────────────┐     ┌──────────────┐
                 │ Rate Limiter │     │ Role Resolver │
                 └──────┬───────┘     └──────┬───────┘
                        │                     │
                        ▼                     ▼
                 ┌──────────────┐     ┌──────────────┐
                 │  Audit Log   │     │  Permission   │
                 │              │     │    Check      │
                 └──────────────┘     └──────────────┘

OAuth2 / OIDC via Square IdP

For interactive sessions (dashboard), AxiomDB delegates to Square's identity provider:

  1. User clicks "Sign in with Square".
  2. Browser redirects to Square IdP with OIDC parameters.
  3. User authenticates (MFA if required).
  4. IdP returns an authorization code.
  5. AxiomDB exchanges the code for tokens.
  6. Session is established with role-appropriate access.

Best Practices

  1. Least privilege: Assign the lowest role that satisfies the member's needs.
  2. Separate billing: Give finance team members the billing role, not owner.
  3. Use API tokens for CI: Never use personal credentials in automation.
  4. Rotate tokens: Set expiry on all API tokens and rotate before they expire.
  5. Audit regularly: Review the team roster and audit log monthly.
  6. Remove promptly: Remove members immediately when they leave the organization.

Troubleshooting

Permission denied

{
  "error": "forbidden",
  "message": "Role 'developer' does not have permission to perform 'network:write'",
  "required_role": "admin"
}

Fix: Ask a project owner or admin to upgrade your role.

Invitation expired

{
  "error": "invitation_expired",
  "message": "This invitation expired on 2026-01-22T10:30:00Z",
  "invited_by": "usr_8xK2mP"
}

Fix: Ask the inviter to send a new invitation.

Cannot remove member

{
  "error": "forbidden",
  "message": "Admins cannot remove other admins. Ask the project owner."
}

Fix: Ask the project owner to remove the admin or downgrade them first.

Network Policy

Understand how network rules interact with role permissions.

Audit Log

Track all team changes in the audit log.

Credential Rotation

Learn which roles can rotate credentials and how.

Network Policy

Control network access to your AxiomDB Postgres instances with CIDR allowlists, port-level rules, and progressive security modes.

Credential Rotation

Rotate Postgres credentials atomically across all layers — database, pooler, and secret store — with zero downtime and full audit trails.

On this page

Teams & RolesRole HierarchyPermission MatrixSensitive ActionsInviting MembersVia DashboardVia CLIVia APIChanging RolesRemoving MembersRole-Specific BehaviorOwnerAdminDeveloperViewerBillingAPI Token ScopesToken scopes referenceAuthentication FlowPASETO v4 TokensOAuth2 / OIDC via Square IdPBest PracticesTroubleshootingPermission deniedInvitation expiredCannot remove memberRelated Pages