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/auth/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/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/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/auth/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/credentials/clients/{id} \
  -H "Authorization: Bearer <access_token>"

Update client roles¶

curl -X PUT https://sandbox.qpay.quecto.com.br/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/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/credentials/roles \
  -H "Authorization: Bearer <access_token>"

Full Credentials API reference¶

See the Credentials API for the complete endpoint reference.