Teams & Roles

Managing who can access your database is simple with AxiomDB. We use project-level role-based access control (RBAC) to keep things secure. When you add team members, you assign them a specific role that dictates exactly what they can and can't do. For extra peace of mind, high-impact actions are protected by confirmation steps and logged in the audit trail.

The Role Hierarchy

AxiomDB roles are arranged in a hierarchy from the most privileged to the least. Members with higher roles inherit all the permissions of the roles below them:

┌──────────────────────────────────────────────────────┐
│                     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 at a Glance

Guarding Sensitive Actions

Some actions have a bigger impact than others. For those, we require extra confirmation steps beyond standard role checks, and we always log these events to your audit trail:

Adding Team Members

Ready to invite new collaborators to your project? Here is how you can do it:

Using the Dashboard

1. Head over to Project Settings → Team.
2. Click the Invite Member button.
3. Enter the person's email address and pick their role.
4. They'll receive an email with a secure invitation link.
5. Keep in mind that invitation links expire after 7 days!

Using the CLI

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

Using the 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 a Member's Role

When you update a team member's role, the change goes into effect immediately. Their active database connections won't be abruptly disconnected, but any new API requests they make will be checked against their updated permissions.

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

Removing a Team Member

Removing someone from a project revokes their access immediately. If they have active database connections running, we'll give them a 60-second grace period so any in-flight queries can finish before we close the connections.

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

Once removed, they'll receive a notification email, and any API tokens they created for this project will be deactivated.

A Deeper Look at Each Role

Owner

The project Owner is the ultimate administrator:

• Opening public network ports: Only owners can switch network modes to public_runtime or public_all. And for public_all, you'll need to type the project name to confirm.
• Deleting the project: This is permanent! To make sure it's intentional, you must type the project name. This will wipe out all data, branches, backups, and team settings.
• Billing control: Owners have full access to update payment methods, download invoices, and manage the subscription plan.
• Passing the torch: An owner can transfer project ownership to another team member. Once done, the previous owner is adjusted to an Admin.

Admin

Admins take care of the project's day-to-day operations:

• Managing branches: Admins can create, delete, and restore branches.
• Controlling the network: Admins are in charge of adding, updating, and removing CIDR rules.
• Rotating credentials: Admins can rotate runtime, direct, or both sets of credentials.
• Restores: Admins can initiate point-in-time restores from backups.
• Team adjustments: Admins can invite new members and manage roles up to the Admin level.

Developer

Developers focus on writing code and building features:

• Branch creation: Developers can spin up new branches (as long as project policy allows it).
• Query execution: Developers have full query access via the dashboard and database clients.
• Credential access: This is conditional and depends on the allow_developer_credential_access policy.
• View access: Developers can view branches, read network rules, and inspect audit logs.

Viewer

Viewers have read-only access to help keep tabs on the project:

• Dashboard access: Viewers can see project metrics, the dashboard, and lists of branches.
• Audit logs: Viewers can inspect the audit log (but cannot export it).
• No changes allowed: Viewers cannot create branches, run database queries, or edit configurations.

Billing

The Billing role is custom-built for accounting and finance team members:

• Payment options: Billing members can add, update, or delete payment details like credit cards.
• Invoices: Billing members can view and download current and past invoices.
• Plan details: Billing members can upgrade, downgrade, or cancel subscriptions.
• No technical access: To keep things secure, billing members cannot see database branches, execute queries, or view connection credentials.

API Token Scopes

When creating API tokens, you can assign them a specific role. The token will inherit the permissions of that role, meaning it can never exceed the access level of the role it's assigned to.

{
  "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

How Authentication Works

AxiomDB supports two secure ways to authenticate:

PASETO v4 Tokens

Our API tokens use the modern PASETO v4 standard, signed securely with Ed25519 keys. We generate these tokens on the server and only display the token value once when you create it. Make sure to copy it down, as we can't show it to you again!

OAuth2 / OIDC via Square Identity Provider

When you log into the web dashboard, we delegate the process to Square's identity provider:

1. You click Sign in with Square.
2. Your browser redirects to the Square Identity Provider using secure OIDC parameters.
3. You authenticate (including Multi-Factor Authentication if it's set up).
4. The provider sends back a secure authorization code.
5. AxiomDB exchanges this code for access tokens.
6. Your dashboard session starts with access levels matching your project role.

Team Management Best Practices

1. Follow the principle of least privilege. Always assign the minimum role required for a team member to do their job.
2. Keep billing roles separate. Give your finance team the Billing role rather than making them project Owners.
3. Use API tokens for automation. Never embed personal login credentials in your CI/CD pipelines—use scoped API tokens instead.
4. Rotate your tokens. Set expirations on your API tokens and rotate them before they run out.
5. Perform regular audits. Take a look at your team roster and project audit logs once a month.
6. Clean up access immediately. Be sure to remove team members from the project as soon as they leave your team or organization.

Troubleshooting Role Issues

Permission denied

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

What went wrong: Your current role doesn't have the permissions required for the action you're trying to perform.

How to fix it: Reach out to a project Owner or Admin and ask them to upgrade your project role.

Invitation expired

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

What went wrong: The invitation link was not accepted within the 7-day window.

How to fix it: Ask the team member who invited you to generate and send a new invitation link.

Cannot remove member

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

What went wrong: Admins are not allowed to remove other admins from the project.

How to fix it: Ask the project Owner to downgrade the admin first, or have the Owner remove them directly.

Related Pages