Team roles and permissions

Everyone on your team has one role. A role is a set of permissions, and every request — from the dashboard or straight to the API with a member’s own sign-in — is checked against it before anything happens. The dashboard hides what your role cannot do; the API refuses it either way.

The roles are Stripe’s, so if you have used Stripe you already know roughly what an analyst or a support account is for. Where we are stricter, it says so below.

The roles

Where we are stricter than Stripe

An analyst changes nothing. They read payments, customers, the balance and events, and they can download reports. They cannot refund, capture, create a payment or a customer, or edit the catalogue.

Support does not see the books. A support account answers one customer at a time: it can refund, capture, take a payment, edit a customer, raise an invoice and answer a dispute. It cannot see the balance, payouts or reports, cannot publish a price or a payment link, and never sees an API key or a webhook.

Only an owner or an admin may write risk rules, change payouts, fill in the activation application (it holds your directors’ identity documents) or manage the team. Only the owner may transfer or close the business.

Actions that ask for your authenticator again

Some actions need a code from your authenticator app from the last ten minutes, not just one from when you signed in. A stolen session would want these first:

keys:live, team:invite, team:manage, payouts:manage, settings:security, risk:manage, account:transfer, account:close, rotating a webhook signing secret, and making a person's declarations on the activation application. Refunds do not: support refunds all day, and a challenge on every one teaches people to approve challenges without reading them.

Two-step verification for live businesses

Once your business is approved for live payments, everyone on the team signs in with an authenticator app as well as their password or passkey. It cannot be turned off while live payments are on. A teammate who has not set one up is asked to when they next sign in.

Changing your password, your email address or your authenticator signs you out on every other device, and so does signing out other devices from your security page — at once, not when the session would have expired.

API keys and permissions

A secret key can do everything the API offers a key — take and refund payments, manage customers, the catalogue, invoices, risk rules, disputes and webhooks, and read the balance, events and reports. It can never create another key, read identity documents or change the team: those are dashboard-only, for a signed-in person.

Nobody can create a key that can do more than they can. A full secret key can refund, so a live one can be created only by an owner or an admin. A developer can create test keys, which move no money. Live keys need a fresh code from your authenticator.

When a request is refused

A request your role or key does not permit is answered with 403, and required_capability names the permission that was missing:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permissions",
    "message": "Your role (analyst) does not have the payments:refund permission.",
    "required_capability": "payments:refund"
  }
}