Authentication

Safefy uses OAuth2 Client Credentials for authentication. You must obtain a JWT token before making any other request.

Credential permissions (module-level read/write, including cashouts) are detailed in Credential permissions.

How it works

Getting the token

curl -X POST https://api-payment.safefypay.com.br/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "client_credentials",
    "publicKey": "pk_sandbox_abc123...",
    "secretKey": "sk_sandbox_xyz789..."
  }'

Response:

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "environment": "Sandbox"
  }
}

Using the token

Include the token in the Authorization header for all requests:

curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The token expires in 1 hour (3600 seconds). Refresh it before expiration to avoid interruptions.

Rate limiting

Token generation is limited to 10 requests per hour per credential pair (publicKey + secretKey). If you exceed this limit, the API returns 429 Too Many Requests with the error code auth_rate_limit_exceeded.

Do not generate a new token on every API call. Cache the token and reuse it for its full 1-hour lifetime. Excessive token generation will trigger the rate limit and block your integration.

Token caching

Implement token caching to avoid unnecessary requests and stay well within the rate limit:

Check if savedToken exists
If yes  check if (expiresAt - 5 minutes) > now
If still valid  reuse savedToken   no API call needed
If expired or not found  call POST /v1/auth/token
Save new token + calculated expiresAt  use it

Treat the token as expired 25 minutes before its actual expiry (expiresIn - 300 seconds). This protects against clock skew between your server and Safefy’s servers.

Security best practices

Never expose the secretKey

Keep the secretKey only on the backend. Never include it in frontend code or public repositories.

Use environment variables

Store credentials in environment variables or secret managers (AWS Secrets Manager, Vault, etc).

Refresh before expiration

Implement logic to refresh the token before the 3600 seconds expire.

Restrict allowed IPs

In the Safefy dashboard, restrict credential usage to your server IPs.

Common errors

Code	Error	Solution
401	Invalid credentials	Check publicKey and secretKey
403	Unauthorized IP	Add the IP in the credential settings
429	Rate limit exceeded	Wait for the time indicated in `Retry-After`

Test authentication

Try the authentication endpoint in the playground.

Introduction

Concepts

API Status

Testing environment

How it works

Getting the token

Using the token

Rate limiting

Token caching

Security best practices

Never expose the secretKey

Use environment variables

Refresh before expiration

Restrict allowed IPs

Common errors

Test authentication

​How it works

​Getting the token

​Using the token

​Rate limiting

​Token caching

​Security best practices

Never expose the secretKey

Use environment variables

Refresh before expiration

Restrict allowed IPs

​Common errors

Test authentication

How it works

Getting the token

Using the token

Rate limiting

Token caching

Security best practices

Common errors