Guide

Authentication

Every request is authenticated with a workspace API key sent as a bearer token. Keys carry scopes, can expire, and are revoked instantly.

Create a key

API keys belong to a workspace, not to a person. A workspace owner or admin creates them under Settings → Developers, giving each key a name, a set of scopes and an optional expiry. The secret is shown once, at creation. Paygoro stores only a hash of it, so a lost key cannot be recovered — create a new one instead.

A secret looks like pgk_ followed by 40 letters and digits. The first characters stay visible in the settings page so you can tell keys apart; the rest never appears again.

Send the key

Put the secret in the Authorization header as a bearer token on every request:

curl https://api.paygoro.com/v1/workspace \
  -H "Authorization: Bearer pgk_…"

GET /workspace is the connectivity check: it requires no scope and returns the workspace plus the scopes the key carries, so you can verify a deployment before wiring anything else up.

A missing, malformed, revoked or expired key gets a 401 UNAUTHORIZED whose message says which of those it was.

Scopes

Scopes are resource:verb pairs. Give an integration the smallest set that does its job — an accounting sync reads transactions and never needs to write payees. A request for an operation the key is not allowed to perform returns 403 FORBIDDEN and names the scope it needed:

{
  "defined": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "This API key is missing the `payees:write` scope.",
  "data": {
    "requiredScopes": [
      "payees:write"
    ]
  }
}

Each operation in the reference lists the scope it requires. The OpenAPI document carries the same information in the x-required-scopes extension.

Workspaces and companies

A key sees exactly one workspace. Inside it there may be several legal entities — Paygoro calls them companies — and each account, transaction, bill and payee belongs to one. Lists span the whole workspace by default; pass companyId to narrow to a single entity. Use GET /companies to discover the ids.

Rotation and revocation

• Rotate by creating a new key, deploying it, then revoking the old one. Both stay valid in between, so rotation needs no downtime.
• Revocation is immediate. The next request with a revoked key fails with 401.
• Expiry is optional (30, 90 or 365 days). An expired key also fails with 401; it is not deleted, so the settings page still shows what it was.