Skip to main content
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:
WildcardDescription
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

CategoryPermissionsDescription
Useruser.create, user.list, user.view, user.edit, user.delete, user.*User management
Rolerole.create, role.list, role.edit, role.delete, role.*Role management
Companycompany.list, company.edit, company.*Company profile
Transactiontransaction.create, transaction.list, transaction.view, transaction.refund, transaction.*Organization transactions
Bankingbanking.list, banking.create, banking.view, banking.*Balance, statement, cashouts, transfers
Affiliationaffiliation.create, affiliation.list, affiliation.view, affiliation.*Organization affiliations
PIXpix.create, pix.list, pix.delete, pix.*PIX keys
Ledgerledger.list, ledger.view, ledger.*Ledger entries
Fee Policyfee_policy.create, fee_policy.list, fee_policy.edit, fee_policy.*Pricing policies
Webhookwebhook.list, webhook.*Webhook dashboard
Merchantmerchant.*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"

​
Next steps

Authentication

Learn about authentication methods

API Reference

Explore user management endpoints