Team Roles
Give team members built-in or custom roles, and manage your team through the API.
Every team member has one role. The role decides what they can do in the Dashboard and in CLI sessions. You can manage roles and team members in the Dashboard or with the team endpoints.
Built-in and custom roles
Dots has built-in roles such as admin, viewer, payer, ap_approver and ap_creator. admin can do everything. The full list is in the built-in-role schema of the API reference.
A custom role is a named list of actions, such as create_payout or view_payouts_tab. Create one with Create a Custom Role:
{
"name": "Payout operator",
"actions": ["get", "create_payout", "view_payouts_tab"]
}A custom role cannot include manage_keys, deposit_ach or edit_authorized_users. Only admins can manage API keys, deposit by ACH, or manage the team.
Role names must be unique within an App or organization. Changing a role’s actions applies right away to everyone who has it.
App and organization teams
An App and an organization each have their own team and their own custom roles.
- Organization members have access to every App in the organization.
- App routes (
/v2/roles,/v2/developers,/v2/developer-invites) manage one App’s team. Use an App API key, or an organization API key with theApi-App-Idheader. - Organization routes (
/v2/organizations/roles,/v2/organizations/developers,/v2/organizations/developer-invites) manage the organization’s team. They need an organization API key withoutApi-App-Id. GET /v2/developerslists the App’s members and the organization’s members. Organization members havescope: organizationand can only be changed through the organization routes.- A custom role can only be given to members of the App or organization it belongs to.
Assigning roles
Change a member’s role with Change a Developer’s Role. Send either a built-in role or a custom role:
{ "role": "payer" }{ "custom_role_id": "8a5f8a7e-1b0f-4f4b-9b2e-3c8d6f1e2a90" }Use the member’s id from the list endpoint. Setting one field clears the other.
An App or organization must always keep at least one admin. Dots rejects a role change or removal that would leave it without one.
A custom role that is assigned to a member or a pending invite cannot be deleted. Move those members to another role first.
Invites
Invite a Developer emails an invite link with a role:
{
"email": "jane@example.com",
"custom_role_id": "8a5f8a7e-1b0f-4f4b-9b2e-3c8d6f1e2a90"
}The invite expires after seven days. The person gets the role when they accept, and the link only works for the invited email address. You can’t invite someone who is already on the team or already has a pending invite. Cancel a pending invite with Cancel a Developer Invite.
Where roles are enforced
- API key requests ignore roles. An API key is not tied to a team member, so it can call any endpoint its App or organization can use. A read-only key can only make
GETrequests. - CLI sessions use the member’s role. A session from
dots loginacts as the team member who signed in. Each request is checked against their role, so changing the role changes what their CLI sessions can do. Managing the team from the CLI needs theadminrole. - Accounts payable checks the acting user. Payable endpoints take an
acting_user_id, which is a team memberid. Creating, updating, canceling and submitting a payable needsap_create_payable. Paying one needsap_initiate_payment. Everyone in an approval policy’sapprover_listmust haveap_approve_payablewhen the policy is created.
Before you remove an action from a role, check whether anyone with that role is used as an acting_user_id or an approver.