Scopes and permissions
What each API scope grants, and which are restricted.
Every token — team API key or OAuth access token — carries scopes that gate what it can do. An endpoint that is called without its scope fails with 403 MISSING_SCOPE.
Scopes
| Scope | Grants |
|---|---|
team:read | Read the team, its accounts (balances and deposit instructions), and members |
payouts:read | List and read payouts |
payouts:write | Create, update, and delete payouts; send claim links; pay approved payouts to a counterparty |
payouts:approve | Approve payouts, on POST /payouts/{id}/approve or with andThen on create; pay a failed payout again. Restricted — only granted to admin-provisioned OAuth clients and to API keys for teams with the payout.api_approve permission. Not available via dynamic client registration. |
counterparties:read | List and read counterparties, countries, and payment method types |
counterparties:write | Create, update, and delete counterparties; read countries and payment method types |
webhooks:read | List webhooks and their deliveries |
webhooks:write | Create, update, delete, and test webhooks; rotate their secrets. An event carries its resource in full, so subscribing to payout events also needs payouts:read, and to counterparty events counterparties:read. |
sessions:write | Mint hosted session URLs (granted by default) |
For OAuth, include offline_access in the scope list to receive a refresh token.
Which team does a token act on?
- A team API key is scoped to the team that owns the key.
- An OAuth access token is scoped to the team the user selected during authorization, carried in the
https://talentir.com/oauth/team_idclaim. For platforms this is usually a customer's team, not your own. - An OAuth token's effective scopes shrink to what the authorizing member's current role allows. A member's token never carries
payouts:approve, and a demoted member's token loses it on its next request.
Safety model
payouts:write alone can never move money: a created payout stays created until a team member approves it (see Approve payouts). Approval reserves the funds and always requires either the restricted payouts:approve scope or an explicit human approval backed by the team's passkey wallet and daily allowance.
Paying an approved payout to a counterparty (POST /payouts/{id}/pay) needs only payouts:write, because it moves what approval already reserved, to the destination approval already covered.
Paying a failed payout again also needs payouts:approve. The money goes to the counterparty's current payment method, which can have changed since approval.