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.