Rinne API Documentation

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] 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.

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

Store API keys securely

Use environment variables for API keys
Never commit keys to version control
Rotate keys periodically
Use different keys for sandbox and production

Use HTTPS only

All API requests must use HTTPS. HTTP requests will be rejected.

Implement rate limiting

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
  }
}

Getting started

Core concepts

Guides

Authentication

API key authentication

Getting your API key

For organizations

For merchants

Authentication scope

Organization scope

Merchant scope

User authentication (JWT)

JWT token structure

Password management

First access

Forgot password

Change password

Security best practices

Error responses

Next steps

Create your first transaction

User management

​API key authentication

​Getting your API key

​For organizations

​For merchants

​Authentication scope

​Organization scope

​Merchant scope

​User authentication (JWT)

​Login flow

​JWT token structure

​Password management

​First access

​Forgot password

​Change password

​Security best practices

​Error responses

​Next steps

Create your first transaction

User management

API key authentication

Getting your API key

For organizations

For merchants

Authentication scope

Organization scope

Merchant scope

User authentication (JWT)

Login flow

JWT token structure

Password management

First access

Forgot password

Change password

Security best practices

Error responses

Next steps