DotsDocs
Guides

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 the Api-App-Id header.
  • Organization routes (/v2/organizations/roles, /v2/organizations/developers, /v2/organizations/developer-invites) manage the organization’s team. They need an organization API key without Api-App-Id.
  • GET /v2/developers lists the App’s members and the organization’s members. Organization members have scope: organization and 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 GET requests.
  • CLI sessions use the member’s role. A session from dots login acts 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 the admin role.
  • Accounts payable checks the acting user. Payable endpoints take an acting_user_id, which is a team member id. Creating, updating, canceling and submitting a payable needs ap_create_payable. Paying one needs ap_initiate_payment. Everyone in an approval policy’s approver_list must have ap_approve_payable when 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.