Skip to main content
Rinne uses API key authentication for secure access to the platform. Each company (organization or merchant) has a unique API key that grants access to their resources.

​
API key authentication

Include your API key in the x-api-key header for all requests: 
curl https://api-sandbox.rinne.com.br/core/v1/companies/me \
  -H "x-api-key: YOUR_API_KEY"
Keep your API keys secure. Never commit them to version control or expose them in client-side code.

​
Getting your API key

​
For organizations

Organizations receive their API key when their account is created by Rinne administrators. Contact support@rinne.com.br to get started.

​
For merchants

When you create a merchant through the API, the response includes the merchant’s API key: 
{
  "id": "merchant-123",
  "name": "My Store",
  "api_key": "ak_98765432101234567890123456789012",
  ...
}

​
Authentication scope

Your API key determines what resources you can access:

​
Organization scope

Organization API keys can access:
  • All merchants under the organization
  • Aggregated transaction data
  • Organization-level settings
  • Pricing policies
  • User management across merchants
# Organization can access all merchants
GET /v1/merchants

# Organization can view all merchant transactions
GET /v1/merchants/transactions

​
Merchant scope

Merchant API keys can only access:
  • Own merchant data
  • Own transactions
  • Own affiliations and PIX keys
  • Own banking information
# Merchant can only access own data
GET /v1/transactions
GET /v1/affiliations

​
User authentication (JWT)

For user-facing applications, Rinne provides JWT-based authentication for individual users.

​
Login flow

  1. User login: Authenticate with email/phone and password
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "password": "SecurePassword123"
  }'
  1. Company selection: If user has multiple companies, select one
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/select-company \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "company-123"
  }'
  1. Use JWT token: Include token in Authorization header
curl https://api-sandbox.rinne.com.br/core/v1/auth/me \
  -H "Authorization: Bearer JWT_TOKEN"

​
JWT token structure

JWT tokens include:
  • User ID and identifiers
  • Selected company context
  • User permissions and roles
  • Token expiration time

​
Password management

​
First access

New users receive a verification code via email: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "code": "123456",
    "password": "SecurePassword123"
  }'

​
Forgot password

Request a password reset code: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com"
  }'
Reset password with the code: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "code": "123456",
    "new_password": "NewSecurePassword123"
  }'

​
Change password

Authenticated users can change their password: 
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/change-password \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "CurrentPassword123",
    "new_password": "NewSecurePassword123"
  }'

​
Security best practices

  • Use environment variables for API keys
  • Never commit keys to version control
  • Rotate keys periodically
  • Use different keys for sandbox and production
All API requests must use HTTPS. HTTP requests will be rejected.
Implement exponential backoff for retries and respect rate limits to avoid throttling.
When receiving webhooks, validate the signature to ensure requests are from Rinne.

​
Error responses

Authentication errors return a 401 status code: 
{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key",
    "status": 401
  }
}
Authorization errors return a 403 status code: 
{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You don't have permission to access this resource",
    "status": 403
  }
}

​
Next steps

Create your first transaction

Follow the quickstart guide

User management

Manage users and permissions