Credentials & Authentication¶

QPay uses OAuth2 client credentials for machine-to-machine API authentication. Your application exchanges a client_id and client_secret for a short-lived JWT access token, which it includes on every API request.

Prerequisites¶

You must have completed Step 1 and Step 2 of the developer guide — your tenant exists and you have logged in at least once to set your password.

Creating client credentials¶

Client credentials are created via the Credentials API. You authenticate to this API with your personal user token (not a client credential) to bootstrap the first credential.

1. Sign in and get a user token¶

Authenticate with your username and password using the OAuth2 password grant:

curl -X POST https://sandbox.qpay.quecto.com.br/realms/qpay/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=qpay-console" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD"

Save the access_token from the response. It is valid for 5 minutes.

2. Find your tenant ID¶

curl https://sandbox.qpay.quecto.com.br/api/credentials/whoami \
  -H "Authorization: Bearer <access_token>"

Response:

{
  "tenant_type": "issuer",
  "tenant_id": "your-tenant-id",
  "parent_tenant_id": "parent-processor-tenant-id"
}

Save the tenant_id — you will need it in the next step.

3. Create a client¶

curl -X POST https://sandbox.qpay.quecto.com.br/api/credentials/clients \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "your-tenant-id",
    "name": "my-integration-client",
    "roles": ["issuer"]
  }'

Response:

{
  "id": "internal-record-id",
  "client_id": "abc123...",
  "client_secret": "supersecret...",
  "tenant_id": "your-tenant-id"
}

Obtaining an access token¶

Once you have a client_id and client_secret, your application obtains tokens autonomously using the OAuth2 client credentials grant — no user interaction required:

curl -X POST https://sandbox.qpay.quecto.com.br/realms/qpay/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGci...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Pass the token on every API call:

Authorization: Bearer eyJhbGci...

Token expiry¶

Tokens expire after 300 seconds (5 minutes). Your application should request a new token before the current one expires. A simple strategy is to re-fetch a token before each API call or cache it and refresh when expires_in - 30 seconds have elapsed.

Managing credentials¶

List your clients¶

curl https://sandbox.qpay.quecto.com.br/api/credentials/clients/{id} \
  -H "Authorization: Bearer <access_token>"

Update client roles¶

curl -X PUT https://sandbox.qpay.quecto.com.br/api/credentials/clients/{id} \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"roles": ["issuer"]}'

Delete a client¶

curl -X DELETE https://sandbox.qpay.quecto.com.br/api/credentials/clients/{id} \
  -H "Authorization: Bearer <access_token>"

Available roles¶

The roles available to your client depend on your tenant type. Query the roles endpoint to see what your tenant can assign:

curl https://sandbox.qpay.quecto.com.br/api/credentials/roles \
  -H "Authorization: Bearer <access_token>"

Product, layout and card roles¶

Card issuance is gated the same way: fine-grained, issuer-scoped roles, each with a manage-* superset and narrower verbs beneath it. A client holding manage-product, manage-layout and manage-card can run the whole flow; grant less where the job is narrower.

Setting up an offering — see Manage Card Products:

Issuing and running cards — see Create a Card:

Ledger roles¶

Ledger operations are gated by their own fine-grained roles, all issuer-scoped. They are not implied by the broad issuer role — assign them explicitly to the client that needs them.

Configuring where QPay sends authorization — see Connect Your Own Ledger:

Using QPay's internal ledger — see Use the QPay Ledger:

Credit invoicing — see Run a Billing Cycle:

Full Credentials API reference¶

See the Credentials API for the complete endpoint reference.