Team & roles API

Invite people to your account and control what they can do with roles. A role is a named bundle of permissions; you assign one to each member (and, with the same model, to API keys).

All endpoints need a bearer token. In practice team, role, and account management is Owner work done from a login session - API keys can never hold team, roles, or account permissions.

For the concept-level overview, see Team & roles.

Owner vs member

• The Owner is whoever registered the account. They have full access to everything, implicitly - no role to assign, nothing to configure.
• Everyone else is a Member with exactly one assigned role. Their access is whatever that role grants, and nothing more.

Permission tokens

A permission is a resource:action string, for example pods:read or billing:pay. A wildcard resource:* grants every action on that resource (pods:*). Roles are built from these tokens.

A few actions are more sensitive than the rest - grant them deliberately:

• pods:console - open a shell inside a pod
• domains:ssl - issue and manage SSL certificates
• billing:pay - spend money (top up credit)

The permission catalogue

GET /api/permissions

Returns every resource and the actions it supports - the source of truth for what you can put in a role:

{
  "resources": [
    { "key": "pods", "label": "Pods", "actions": ["read", "create", "update", "delete", "console"] }
  ]
}

The 16 resources and their actions:

Resource	Actions
pods	read, create, update, delete, console
networks	read, create, update, delete
firewalls	read, create, update, delete
domains	read, create, update, delete, ssl
snapshots	read, create, update, delete
backups	read, create, update, delete
email	read, create, update, delete
sshkeys	read, create, delete
monitoring	read, update
billing	read, pay
support	read, create, update
apikeys	read, create, delete
roles	read, create, update, delete
team	read, create, update, delete
account	read, update
audit	read

Roles

List roles

GET /api/roles/

Returns your account's roles, including the four seeded system roles. A Role looks like:

{
  "id": "...",
  "name": "Deployer",
  "description": "Can manage pods and domains",
  "permissions": ["pods:*", "domains:read", "domains:update"],
  "isSystem": false,
  "createdAt": "..."
}

System roles

Every account starts with four ready-made roles. They are marked isSystem: true and cannot be edited or deleted:

Role	Grants
Full access	Everything except team, roles, and account settings. The Owner always has those; a custom role can grant them too if you want to delegate.
Developer	Manage pods, networks, firewalls, domains, snapshots, backups, SSH keys, monitoring, and support; read-only email and activity log.
Read-only	The read action on everything. Look, don't touch.
Billing	Full billing; read-only account and activity log.

Create a role

POST /api/roles/

{
  "name": "Deployer",
  "description": "Can manage pods and domains",
  "permissions": ["pods:*", "domains:read", "domains:update"]
}

Returns 201 with the new role. You can only grant permissions you hold yourself.

Update a role

PUT /api/roles/:roleId

{
  "name": "Deployer",
  "description": "Pods, domains, and now snapshots",
  "permissions": ["pods:*", "domains:*", "snapshots:*"]
}

Only your own custom roles - system roles are read-only.

Delete a role

DELETE /api/roles/:roleId

Team members

List members

GET /api/team/

Invite a member

POST /api/team/

{
  "username": "bob",
  "firstName": "Bob",
  "lastName": "Lee",
  "email": "bob@example.com",
  "roleId": "<role id>"
}

Sends an email invitation. The invited person clicks the link and sets their own password - you never see or set a temporary one. Leave roleId empty and they start on the least-privilege Read-only role, which you can change later. Returns 201.

Change a member's role

PATCH /api/team/:userId/role

{ "roleId": "<role id>" }

Enable or disable a member

PATCH /api/team/:userId/status

{ "isActive": false }

Disabling a member blocks their access without removing them - handy for someone who is away for a while.

Remove a member

DELETE /api/team/:userId

Removes them from the account and revokes any API keys they created.

Example

curl -X POST https://cloud-api.microapps.io/api/team/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"bob","firstName":"Bob","lastName":"Lee","email":"bob@example.com","roleId":"<role id>"}'