Skip to content
Baiyar DocsBaiyar DocsBaiyar Docs

Permissions

What each permission of an API key allows, which operation needs which, and what happens without it.

A key only does what it was given, as resource:action pairs. A write permission includes the matching read: a key that may change a resource can also see it. You choose the permissions when you create the key in the dashboard; give it only what your server needs.

Permission types

Section titled “Permission types”
  • Read (:read) lets a key see a resource: get one, list them.
  • Write (:write) lets a key create and change it, and includes read.

Available permissions

Section titled “Available permissions”
Permission Allows
payments:read Read payments (their timeline and attempts), payment links and the analytics report
payments:write Create and cancel payments, create and cancel payment links, simulate a test payment (and everything payments:read allows)
invoices:read Read invoices
invoices:write Make, change, issue, void, resend and delete invoices. Issuing mails your customer in live (and everything invoices:read allows)
webhooks:read Read events, event types, webhook endpoints and their deliveries
webhooks:write Create, change, delete and test webhook endpoints, and rotate their secrets (and everything webhooks:read allows)
balances:read Read the balance and its movements, and the statement, ledger, reconciliation and settlements reports (merchant keys only)
payouts:read, payouts:write Reserved. There is no payout operation yet, and payouts:write is for project keys only

Operations and the permission they need

Section titled “Operations and the permission they need”
Operation Endpoint Permission
Get account GET /v1/account none: any valid key
Create a payment POST /v1/payments payments:write
List payments GET /v1/payments payments:read
Get a payment GET /v1/payments/{id} payments:read
Get a payment timeline GET /v1/payments/{id}/timeline payments:read
List payment attempts GET /v1/payments/{id}/attempts payments:read
Cancel a payment POST /v1/payments/{id}/cancel payments:write
Simulate a payment POST /v1/sandbox/payments/{id}/simulate payments:write
Create a payment link POST /v1/payment-links payments:write
List payment links GET /v1/payment-links payments:read
Get a payment link GET /v1/payment-links/{id} payments:read
Cancel a payment link POST /v1/payment-links/{id}/cancel payments:write
Create an invoice POST /v1/invoices invoices:write
List invoices GET /v1/invoices invoices:read
Get an invoice GET /v1/invoices/{id} invoices:read
Update a draft invoice PUT /v1/invoices/{id} invoices:write
Delete a draft invoice DELETE /v1/invoices/{id} invoices:write
Issue an invoice POST /v1/invoices/{id}/issue invoices:write
Void an invoice POST /v1/invoices/{id}/void invoices:write
Resend an invoice POST /v1/invoices/{id}/resend invoices:write
List payment methods GET /v1/payment-methods none: any valid key
Get payment limits GET /v1/payment-limits none: any valid key
Preview fees POST /v1/fee-preview none: any valid key
List projects GET /v1/projects none: any valid key
Get a project GET /v1/projects/{id} none: any valid key
Get a statement GET /v1/reports/statement balances:read
Get the ledger GET /v1/reports/ledger balances:read
Get the reconciliation GET /v1/reports/reconciliation balances:read
Get the settlements GET /v1/reports/settlements balances:read
Get the analytics GET /v1/reports/analytics payments:read
Get balance GET /v1/balance balances:read
List balance movements GET /v1/balance/movements balances:read
List event types GET /v1/event-types webhooks:read
List events GET /v1/events webhooks:read
Get an event GET /v1/events/{id} webhooks:read
List webhook deliveries GET /v1/webhook-deliveries webhooks:read
Get a webhook delivery GET /v1/webhook-deliveries/{id} webhooks:read
Resend a webhook delivery POST /v1/webhook-deliveries/{id}/resend webhooks:write
List webhook endpoints GET /v1/webhook-endpoints webhooks:read
Create a webhook endpoint POST /v1/webhook-endpoints webhooks:write
Get a webhook endpoint GET /v1/webhook-endpoints/{id} webhooks:read
Update a webhook endpoint PATCH /v1/webhook-endpoints/{id} webhooks:write
Delete a webhook endpoint DELETE /v1/webhook-endpoints/{id} webhooks:write
Rotate an endpoint secret POST /v1/webhook-endpoints/{id}/rotate-secret webhooks:write
Send a test event POST /v1/webhook-endpoints/{id}/test webhooks:write

When a permission is not needed

Section titled “When a permission is not needed”

GET /v1/account, GET /v1/projects, GET /v1/payment-methods, GET /v1/payment-limits and POST /v1/fee-preview need no permission: any valid key can call them, because they describe your account and what is on sale, not a payment. GET /v1/account answers with the permissions of the key you used (key.scopes), so it is the quickest way to check what a key can do.

Without the permission

Section titled “Without the permission”

A call the key is not allowed to make answers 403 insufficient_scope, before anything is done:

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "detail": "This API key does not have the permission this request needs.",
    "documentation_url": "https://docs.baiyar.com/resources/errors/insufficient_scope/"
  },
  "meta": {
    "request_id": "req_…"
  }
}

Two operations need a merchant key, whatever the permissions: the balance belongs to the merchant, so a project key gets 403 forbidden on GET /v1/balance and GET /v1/balance/movements; and a webhook endpoint for the whole merchant (scope: "merchant") can only be created with a merchant key.

Best practices

Section titled “Best practices”
  • Give each key the least it needs: a server that only creates payments needs payments:write and nothing else.
  • Use a separate key for each service, so a leak of one gives away little.
  • To grow a key’s powers, make a new key with the new permissions and rotate the old one out.
Section titled “Related pages”