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

# Authentication

> Learn how to authenticate with the Rinne API

Rinne uses API key authentication for secure access to the platform. Each company (organization or merchant) has a unique API key that grants access to their resources.

## API key authentication

Include your API key in the `x-api-key` header for all requests:

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

<Warning>
  Keep your API keys secure. Never commit them to version control or expose them in client-side code.
</Warning>

## Getting your API key

### For organizations

Organizations receive their API key when their account is created by Rinne administrators. Contact [support@rinne.com.br](mailto:support@rinne.com.br) to get started.

### For merchants

When you create a merchant through the API, the response includes the merchant's API key:

```json theme={null}
{
  "id": "merchant-123",
  "name": "My Store",
  "api_key": "ak_98765432101234567890123456789012",
  ...
}
```

## Authentication scope

Your API key determines what resources you can access:

### Organization scope

Organization API keys can access:

* All merchants under the organization
* Aggregated transaction data
* Organization-level settings
* Pricing policies
* User management across merchants

```bash theme={null}
# Organization can access all merchants
GET /v1/merchants

# Organization can view all merchant transactions
GET /v1/merchants/transactions
```

### Merchant scope

Merchant API keys can only access:

* Own merchant data
* Own transactions
* Own affiliations and PIX keys
* Own banking information

```bash theme={null}
# Merchant can only access own data
GET /v1/transactions
GET /v1/affiliations
```

## User authentication (JWT)

For user-facing applications, Rinne provides JWT-based authentication for individual users.

### Login flow

1. **User login**: Authenticate with email/phone and password

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "password": "SecurePassword123"
  }'
```

2. **Company selection**: If user has multiple companies, select one

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

3. **Use JWT token**: Include token in Authorization header

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

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

### Forgot password

Request a password reset code:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com"
  }'
```

Reset password with the code:

```bash theme={null}
curl -X POST https://api-sandbox.rinne.com.br/core/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user@company.com",
    "code": "123456",
    "new_password": "NewSecurePassword123"
  }'
```

### Change password

Authenticated users can change their password:

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

<AccordionGroup>
  <Accordion title="Store API keys securely">
    * Use environment variables for API keys
    * Never commit keys to version control
    * Rotate keys periodically
    * Use different keys for sandbox and production
  </Accordion>

  <Accordion title="Use HTTPS only">
    All API requests must use HTTPS. HTTP requests will be rejected.
  </Accordion>

  <Accordion title="Implement rate limiting">
    Implement exponential backoff for retries and respect rate limits to avoid throttling.
  </Accordion>

  <Accordion title="Validate webhook signatures">
    When receiving webhooks, validate the signature to ensure requests are from Rinne.
  </Accordion>
</AccordionGroup>

## Error responses

Authentication errors return a 401 status code:

```json theme={null}
{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key",
    "status": 401
  }
}
```

Authorization errors return a 403 status code:

```json theme={null}
{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You don't have permission to access this resource",
    "status": 403
  }
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Create your first transaction" icon="rocket" href="/quickstart">
    Follow the quickstart guide
  </Card>

  <Card title="User management" icon="users" href="/guides/user-management">
    Manage users and permissions
  </Card>
</CardGroup>