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 JWT-authenticated users.

API key authentication bypasses permission checks for most endpoints.

Built-in roles

Rinne provides default roles:

admin: Full access to all resources (uses *.* wildcard)
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"
    ]
  }'

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)
`.`	All permissions (used for organization admin roles)

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.list`, `company.edit`, `company.*`	Company profile
Transaction	`transaction.create`, `transaction.list`, `transaction.view`, `transaction.refund`, `transaction.*`	Organization transactions
Banking	`banking.list`, `banking.create`, `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.delete`, `pix.*`	PIX keys
Ledger	`ledger.list`, `ledger.view`, `ledger.*`	Ledger entries
Fee Policy	`fee_policy.create`, `fee_policy.list`, `fee_policy.edit`, `fee_policy.*`	Pricing policies
Webhook	`webhook.list`, `webhook.*`	Webhook dashboard
Merchant	`merchant.*`	All merchant-scoped operations

Merchant sub-resources:

merchant.company.*: Merchant CRUD
merchant.transaction.*: Merchant transactions
merchant.banking.*: Merchant balance, cashouts, bank accounts
merchant.affiliation.*: Merchant affiliations
merchant.pix.*: Merchant PIX keys
merchant.ledger.*: Merchant ledger entries

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

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

​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

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