> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# User management

> Manage users, roles, and permissions

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

```bash theme={null}
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": "user@company.com"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "auth_methods": ["PASSWORD"],
    "roles": ["admin"]
  }'
```

### For a specific merchant

```bash theme={null}
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": "merchant.user@store.com"
      }
    ],
    "first_name": "Jane",
    "last_name": "Smith",
    "auth_methods": ["PASSWORD"],
    "roles": ["merchant-admin"]
  }'
```

## User identifiers

Users can have multiple identifiers for authentication:

### Email identifier

```json theme={null}
{
  "type": "EMAIL",
  "value": "user@company.com"
}
```

### Phone identifier

```json theme={null}
{
  "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.

<Note>
  API key authentication bypasses permission checks for most endpoints.
</Note>

### 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:

```bash theme={null}
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

```bash theme={null}
curl https://api-sandbox.rinne.com.br/core/v1/permissions \
  -H "Authorization: Bearer JWT_TOKEN"
```

Filter by resource:

```bash theme={null}
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:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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"]
  }'
```

<Note>
  Providing the `roles` array replaces all existing roles. Pass an empty array `[]` to remove all roles.
</Note>

## Multi-company access

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

```bash theme={null}
# 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

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

### Merchant users

```bash theme={null}
curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/users" \
  -H "x-api-key: YOUR_API_KEY"
```

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    Learn about authentication methods
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore user management endpoints
  </Card>
</CardGroup>