Members and Roles

Roles and Permissions

Every member of an organization has exactly one role. Roles determine what a member can see and do.

Role	org:manage_members	org:manage_roles	org:update	org:delete	org:view_billing	Service admin	Service create/update
owner	Yes	Yes	Yes	Yes	Yes	Yes	Yes
admin	Yes	No	Yes	No	Yes	No	Yes
developer	No	No	No	No	No	No	Yes
viewer	No	No	No	No	No	No	No

Service admin includes delete and destructive operations. Developers can create, update, and scale services but cannot delete them.

What Each Role Can Do

Owner: Full control of the organization. Can invite members at any role including owner, transfer ownership, delete the organization, and manage billing.

Admin: Can invite members (but not at owner level), manage most organization settings, view billing, and manage all services. Cannot delete the organization or change other owners' roles.

Developer: Can create and fully manage services, database users, backups, alerts, query statistics, and configurations. Cannot manage members or access billing.

Viewer: Read-only access to services, database users (no password reveal), backups, alerts, logs, and query statistics.

API Token Scopes and Roles

Member roles govern what a person can do through the dashboard and API. API tokens further refine that access by restricting which resource families and permission levels a token can act on. A token minted by a developer cannot exceed that member's own role permissions, regardless of the scopes requested.

The diagram below shows how the API authorizer evaluates incoming token requests against the scope each endpoint requires:

Scoped token enforcement

VERDICT token: services:write + backups:read

Scoped Tokenservices:write · backups:readauthorize →

services:read200services:write200services:admin403backups:read200backups:write403

Organization (mints)Scoped tokenGranted scopeAPI authorizer200 allowed403 insufficient_scope

A developer with a token scoped to services:write can create and update services, but that same token is denied on services:admin endpoints (delete) because write does not subsume admin. To understand the full scope taxonomy, see API Token Scopes.

Inviting Members

Invitations are email-based. The invitee must already have a FoundryDB account. A confirmation email with a time-limited accept link is sent automatically.

Owners and admins can send invitations. Only owners can invite at the owner role.

curl -u user:password -X POST \
  https://api.foundrydb.com/organizations/{orgId}/invites \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "developer"
  }'

The response includes the invite ID, the invited email address, the assigned role, and an expiry timestamp. Invites expire after 7 days if not accepted.

Listing Pending Invites

curl -u user:password \
  https://api.foundrydb.com/organizations/{orgId}/invites

Returns all invites that have been sent but not yet accepted.

Cancelling an Invite

curl -u user:password -X DELETE \
  https://api.foundrydb.com/organizations/{orgId}/invites/{inviteId}

Cancellation prevents the invite link from being accepted, even if the recipient still has the email.

Accepting an Invite

The invitee clicks the link in their email, which sends an authenticated request:

curl -u user:password -X POST \
  https://api.foundrydb.com/invites/{token}/accept

On success, the user is added to the organization at the invited role and receives the org ID and name in the response.

Listing Members

Any member of an organization can see who else belongs to it:

curl -u user:password \
  https://api.foundrydb.com/organizations/{orgId}/members

Each entry in the members array includes the member's user ID, username, email, role, and the timestamp when they joined.

Changing a Member's Role

Only owners can change roles. An owner cannot demote themselves if they are the only owner.

curl -u user:password -X PATCH \
  https://api.foundrydb.com/organizations/{orgId}/members/{userId} \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Valid roles: owner, admin, developer, viewer.

Removing a Member

Owners and admins can remove members. Owners cannot be removed by admins. The last owner cannot be removed.

curl -u user:password -X DELETE \
  https://api.foundrydb.com/organizations/{orgId}/members/{userId}

Removing a member does not delete their services. Services created by a removed member continue running under the organization.

Transferring Ownership

Only the current owner can transfer ownership to an existing member of the organization. The target user must already be a member (at any role). After transfer, the previous owner is demoted to admin.

curl -u user:password -X POST \
  https://api.foundrydb.com/organizations/{orgId}/transfer-ownership \
  -H "Content-Type: application/json" \
  -d '{ "new_owner_id": "b2c3d4e5-0000-0000-0000-000000000011" }'

Personal organizations (the one created automatically at registration) cannot be transferred.

Role Assignment Rules

The following constraints always hold:

• Only owners can assign the owner role to another member.
• An owner cannot demote themselves if they are the only owner in the organization.
• The last owner cannot be removed or transferred out of the org until a replacement owner is in place.
• Admins can invite new members at the admin, developer, or viewer level but cannot touch existing owners.
• Developers and viewers cannot manage membership at all.

These rules apply to both the API and the dashboard, and they are enforced server-side regardless of the caller's token scopes.

Dashboard

The organization settings page includes a Members tab for managing invitations and role changes without the API. Owners see an ownership transfer option at the bottom of the settings page.