Rinne API Documentation

Rinne provides a comprehensive user management system with role-based access control (RBAC). Organizations and merchants can create users with specific permissions.

User basics

Users are individuals who can access the Rinne platform through your organization or merchant account. Each user:

Has one or more identifiers (email, phone)
Can belong to multiple companies
Has roles that define their permissions
Can authenticate using password or OAuth

Creating users

For your organization

curl -X POST https://api-sandbox.rinne.com.br/core/v1/users \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      {
        "type": "EMAIL",
        "value": "[email protected]"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "auth_methods": ["PASSWORD"],
    "roles": ["admin"]
  }'

For a specific merchant

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/users \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      {
        "type": "EMAIL",
        "value": "[email protected]"
      }
    ],
    "first_name": "Jane",
    "last_name": "Smith",
    "auth_methods": ["PASSWORD"],
    "roles": ["merchant-admin"]
  }'

User identifiers

Users can have multiple identifiers for authentication:

Email identifier

{
  "type": "EMAIL",
  "value": "[email protected]"
}

Phone identifier

{
  "type": "PHONE",
  "value": "+5511999999999"
}

Users must verify their identifiers before they can log in.

Authentication methods

Users can authenticate using:

PASSWORD: Email/phone and password
GOOGLE: Google OAuth
CLIENT_PLATFORM: Platform-specific authentication

Roles and permissions

Rinne uses a hierarchical permission system with role-based access control (RBAC). Permissions are enforced on all protected API endpoints for both JWT-authenticated users and API key requests.

API keys carry their own set of permissions, configured at creation time. See the Authentication guide for details on creating keys with specific permissions.

Built-in roles

Rinne provides default roles:

admin: Full access to all resources
user: Basic access to view resources
merchant-admin: Full access to merchant resources

Custom roles

Create custom roles with specific permissions:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/roles \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "finance-manager",
    "description": "Can view transactions and banking",
    "permissions": [
      "transaction.list",
      "transaction.view",
      "banking.list",
      "banking.view"
    ]
  }'

Caller grant ceiling. A role can only carry permissions the caller already holds. POST /v1/roles and PUT /v1/roles/{id} reject any permission that the caller’s effective permissions do not grant with 403 AUTHORIZATION_ERROR. This prevents a user with role.create or role.edit from minting a role with elevated permissions and self-assigning it via user.edit.

How the ceiling is evaluated

Role endpoints accept only JWT authentication, so the caller is always a user whose role cannot carry *.* (it is rejected with 400 at role creation). The caller’s effective permissions are checked with the same rules that gate any API request:

A direct match grants the permission (a caller holding transaction.refund can grant transaction.refund).
A resource wildcard covers every action under it (a caller holding transaction.* can grant transaction.refund, transaction.cancel, and any other transaction.<action>).
A rinne.admin holder can grant anything.
A session with no permissions fails closed.

On PUT /v1/roles/{id}, the check runs against the entire submitted permissions array, not just the diff. A role that already carries a permission the caller does not hold cannot be edited by that caller without first dropping that permission.

Unknown permission names still return 400 VALIDATION_ERROR from the catalog check, which runs before the ceiling check. If you get a 403, the name is valid but you don’t hold it.

Example rejection when a caller holding only role.create and user.list tries to mint a role granting transaction.refund:

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "Caller cannot grant permissions they do not hold: transaction.refund"
  }
}

To grant a permission to another user, first make sure your own role covers it — either directly or through a resource wildcard such as transaction.* or merchant.*.

Permission format

Permissions follow a hierarchical dot-separated format: resource[.subresource].action Basic permissions:

transaction.list: List transactions
transaction.create: Create transactions
user.edit: Edit users

Nested resource permissions (for merchant-scoped operations):

merchant.company.create: Create merchant companies
merchant.transaction.list: List merchant transactions
merchant.banking.view: View merchant banking data

Wildcard permissions

Wildcards grant access to multiple actions at once:

Wildcard	Description
`resource.*`	All actions for a resource (e.g., `user.*` grants `user.create`, `user.list`, etc.)
`resource.subresource.*`	All actions for a sub-resource (e.g., `merchant.company.*`)
`merchant.*`	All merchant-scoped operations (cascades to all sub-resources)

Permission categories

Category	Permissions	Description
User	`user.create`, `user.list`, `user.view`, `user.edit`, `user.delete`, `user.*`	User management
Role	`role.create`, `role.list`, `role.edit`, `role.delete`, `role.*`	Role management
Company	`company.create`, `company.list`, `company.edit`, `company.delete`, `company.*`	Company profile
Transaction	`transaction.create`, `transaction.list`, `transaction.view`, `transaction.refund`, `transaction.cancel`, `transaction.*`	Organization transactions
3DS	`3ds.create`, `3ds.*`	3D Secure session operations
Banking	`banking.list`, `banking.create`, `banking.edit`, `banking.delete`, `banking.view`, `banking.*`	Balance, statement, cashouts, transfers
Affiliation	`affiliation.create`, `affiliation.list`, `affiliation.view`, `affiliation.edit`, `affiliation.*`	Organization affiliations
PIX	`pix.create`, `pix.list`, `pix.view`, `pix.delete`, `pix.*`	PIX keys
Card	`card.create`, `card.list`, `card.view`, `card.delete`, `card.*`	Stored cards
Ledger	`ledger.list`, `ledger.view`, `ledger.*`	Ledger entries
Fee Policy	`fee_policy.create`, `fee_policy.list`, `fee_policy.edit`, `fee_policy.delete`, `fee_policy.*`	Pricing policies
Cost Policy	`cost_policy.create`, `cost_policy.list`, `cost_policy.edit`, `cost_policy.delete`, `cost_policy.*`	System cost policies
Webhook	`webhook.list`, `webhook.*`	Webhook dashboard
API Key	`api_key.create`, `api_key.list`, `api_key.delete`, `api_key.*`	API key management
Merchant	`merchant.*`	All merchant-scoped operations

Merchant sub-resources:

merchant.company.*: Merchant CRUD
merchant.transaction.*: Merchant transactions
merchant.3ds.*: Merchant 3D Secure sessions
merchant.banking.*: Merchant balance, cashouts, bank accounts
merchant.affiliation.*: Merchant affiliations
merchant.pix.*: Merchant PIX keys
merchant.card.*: Merchant stored cards
merchant.ledger.*: Merchant ledger entries
merchant.kyc.*: Merchant KYC check history

Listing available permissions

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

Filter by resource:

curl "https://api-sandbox.rinne.com.br/core/v1/permissions?resource=transaction" \
  -H "Authorization: Bearer JWT_TOKEN"

User lifecycle

1. User creation

Admin creates user with email/phone identifier. User receives verification code.

2. Verification

User verifies their identifier and sets password:

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

3. Active user

User can now log in and access resources based on their roles.

4. Suspension

Admins can suspend users temporarily:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/users/USER_ID/suspend \
  -H "Authorization: Bearer JWT_TOKEN"

5. Reactivation

Suspended users can be reactivated:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/users/USER_ID/activate \
  -H "Authorization: Bearer JWT_TOKEN"

Updating users

Update user information and roles:

curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/users/USER_ID \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Updated",
    "roles": ["admin", "finance-manager"]
  }'

Providing the roles array replaces all existing roles. Pass an empty array [] to remove all roles.

Multi-company access

Users can belong to multiple companies. When logging in, they select which company context to use:

# Login returns available companies
POST /v1/auth/login
{
  "requires_company_selection": true,
  "available_companies": [
    { "id": "company-1", "name": "Company A" },
    { "id": "company-2", "name": "Company B" }
  ]
}

# Select company
POST /v1/auth/select-company
{
  "company_id": "company-1"
}

Listing users

Organization users

curl "https://api-sandbox.rinne.com.br/core/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer JWT_TOKEN"

Merchant users

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/users" \
  -H "x-api-key: YOUR_API_KEY"

Getting started

Core concepts

Guides

User management

User basics

Creating users

For your organization

For a specific merchant

User identifiers

Email identifier

Phone identifier

Authentication methods

Roles and permissions

Built-in roles

Custom roles

How the ceiling is evaluated

Permission format

Wildcard permissions

Permission categories

Listing available permissions

User lifecycle

1. User creation

2. Verification

3. Active user

4. Suspension

5. Reactivation

Updating users

Multi-company access

Listing users

Organization users

Merchant users

Next steps

Authentication

API Reference

​User basics

​Creating users

​For your organization

​For a specific merchant

​User identifiers

​Email identifier

​Phone identifier

​Authentication methods

​Roles and permissions

​Built-in roles

​Custom roles

​How the ceiling is evaluated

​Permission format

​Wildcard permissions

​Permission categories

​Listing available permissions

​User lifecycle

​1. User creation

​2. Verification

​3. Active user

​4. Suspension

​5. Reactivation

​Updating users

​Multi-company access

​Listing users

​Organization users

​Merchant users

​Next steps

Authentication

API Reference

User basics

Creating users

For your organization

For a specific merchant

User identifiers

Email identifier

Phone identifier

Authentication methods

Roles and permissions

Built-in roles

Custom roles

How the ceiling is evaluated

Permission format

Wildcard permissions

Permission categories

Listing available permissions

User lifecycle

1. User creation

2. Verification

3. Active user

4. Suspension

5. Reactivation

Updating users

Multi-company access

Listing users

Organization users

Merchant users

Next steps