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 [email protected]
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
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": "[email protected] ", "password": "SecurePassword123" }'
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" }'
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": "[email protected] ", "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": "[email protected] " }'
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": "[email protected] ", "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.
Validate webhook signatures
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 
