Rinne API Documentation

Rinne supports two authentication methods: API keys for server-to-server integrations and JWT tokens for user-facing applications. Both methods enforce granular permission checks on every request.

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, expose them in client-side code, or share them over insecure channels.

How API keys work

Each API key is:

Hashed on creation — Rinne stores only a SHA-256 hash. The raw key is returned exactly once at creation time (show-once) and can never be retrieved again.
Scoped with permissions — Every key carries its own set of permissions, enforced on every request. By default, keys are created with full access (*.*), but you can restrict them to specific operations.
Optionally time-limited — You can set an expiration date. Expired keys are automatically rejected.
Soft-revocable — Revoked keys stop authenticating immediately but their records are retained for audit.

Authentication scope

Your API key determines which resources you can access based on the company it belongs to:

Organization scope — Organization API keys can access organization-level resources and all merchants under the organization.
Merchant scope — Merchant API keys can only access the merchant’s own resources.

Managing API keys

API key management is available through the API and requires JWT authentication — a leaked API key cannot be used to create or revoke keys, even if it contains permissions for doing so.

API key management endpoints require JWT authentication and the api_key.create, api_key.list, or api_key.delete permissions respectively.

Creating an API key

Authenticate with JWT

You must be authenticated with a JWT token (not an API key) and have the api_key.create permission.

Create the key

curl -X POST https://api-sandbox.rinne.com.br/core/v1/api-keys \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "permissions": ["transaction.create", "transaction.list", "banking.view"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

string

required

A label to identify the key (max 100 characters).

string[]

Permission strings granted to the key. Omit for full access (*.*). Must be valid permissions from the permission catalog.

string

Future ISO 8601 datetime when the key stops authenticating. Omit for a non-expiring key.

Store the raw key securely

The response includes the full key — this is the only time it will be shown:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Production backend",
  "key": "ak_Ab12Cd34Ef56Gh78Ij90Kl12Mn34Op56Qr78x9Zk",
  "prefix": "ak_Ab12",
  "last4": "x9Zk",
  "permissions": ["transaction.create", "transaction.list", "banking.view"],
  "last_used_at": null,
  "expires_at": "2027-01-01T00:00:00Z",
  "revoked_at": null,
  "created_at": "2026-07-30T12:00:00Z"
}

Store the key value immediately in a secure location (e.g., a secrets manager or environment variable). You will not be able to retrieve it again.

Listing API keys

Retrieve your company’s active (non-revoked, non-expired) keys. The raw key is never returned — only the masked prefix and last4 are shown:

curl https://api-sandbox.rinne.com.br/core/v1/api-keys \
  -H "Authorization: Bearer JWT_TOKEN"

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production backend",
    "prefix": "ak_Ab12",
    "last4": "x9Zk",
    "permissions": ["transaction.create", "transaction.list", "banking.view"],
    "last_used_at": "2026-07-30T12:15:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "revoked_at": null,
    "created_at": "2026-07-30T12:00:00Z"
  }
]

Revoking an API key

Revoke a key to immediately stop it from authenticating. Revocation is permanent and cannot be undone:

curl -X DELETE https://api-sandbox.rinne.com.br/core/v1/api-keys/API_KEY_ID \
  -H "Authorization: Bearer JWT_TOKEN"

A successful revocation returns a 204 No Content response.

Managing merchant API keys

Organizations can manage API keys for their merchants using the merchant-scoped endpoints:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/api-keys \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Merchant payment key",
    "permissions": ["transaction.create", "transaction.list"]
  }'

curl https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/api-keys \
  -H "Authorization: Bearer JWT_TOKEN"

curl -X DELETE https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/api-keys/API_KEY_ID \
  -H "Authorization: Bearer JWT_TOKEN"

Limits

Each company (organization or merchant) can have at most 20 active API keys at any time. Active keys are those that are neither revoked nor expired. If you reach the limit, revoke unused keys before creating new ones.

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 or a secrets manager for API keys
Never commit keys to version control
Use scoped permissions — avoid *.* for keys that only need specific operations

Rotate and revoke keys regularly

Set expiration dates on API keys when possible
Revoke keys that are no longer in use
Rotate keys periodically by creating a new key before revoking the old one
If a key is compromised, revoke it immediately via JWT authentication

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

API key management endpoints return a 403 if you attempt to access them with API key authentication instead of JWT. This is a security measure — a leaked API key must not be able to create or revoke other keys.

Getting started

Core concepts

Guides

Authentication

API key authentication

How API keys work

Authentication scope

Managing API keys

Creating an API key

Listing API keys

Revoking an API key

Managing merchant API keys

Limits

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

​How API keys work

​Authentication scope

​Managing API keys

​Creating an API key

​Listing API keys

​Revoking an API key

​Managing merchant API keys

​Limits

​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

How API keys work

Authentication scope

Managing API keys

Creating an API key

Listing API keys

Revoking an API key

Managing merchant API keys

Limits

User authentication (JWT)

Login flow

JWT token structure

Password management

First access

Forgot password

Change password

Security best practices

Error responses

Next steps