Personal access tokens

A personal access token (PAT) lets you read your own Payer data from your own code — no merchant required. It's a bearer token prefixed pat_, issued from Account → Tokens in your Payer dashboard and shown only once. Unlike a merchant key, a PAT belongs to a person, not a business.

What makes a PAT different

• Read-only. PATs carry read scopes only. Money-moving scopes are refused at issuance until per-transaction device confirmation is enforced.
• Personal, never a merchant's. A PAT reads your own activity. Sending an X-Active-Merchant header with a PAT is rejected with a 403 — for merchant API access, issue a secret key from that merchant instead.
• Always expires. You set an expiry when you create one; there is no non-expiring option, and the maximum lifetime is 365 days.

-H "Authorization: Bearer pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Scopes

A PAT can hold any of these read scopes. It reaches only the fields its scopes admit — everything else is denied, even other reads. Grant a token the least it needs.

Reading over GraphQL

Send your PAT as a bearer token to POST /graphql. Each query below is gated on one scope; a token without it gets an authorization error, and a field your token has no scope for is refused outright.

curl https://api.payer.app/graphql \
  -H "Authorization: Bearer pat_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"query { balance { available accountIdentifier } }"}'

balance

query {
  balance {
    available
    accountIdentifier
  }
}

history

query {
  history(first: 20) {
    data {
      id
      transactionType
      partyName
      amount
      status
      createdAt
    }
    paginatorInfo {
      total
      currentPage
      hasMorePages
    }
  }
}

insights

query {
  insights(period: "this_month") {
    balance {
      summary {
        totalMoneyIn
        totalMoneyOut
        leftToSpend
      }
    }
    spending {
      totalSpent
    }
  }
}

Managing tokens

Issue, rotate and revoke PATs from Account → Tokens. Rotating replaces the token immediately; the old value stops working at once. Every issue, rotation and revocation is recorded, and you can see each token's last-used time so a stale one is easy to spot.