# Getting Started

This guide explains how to authenticate with the ORO Bank API and manage your access tokens.

## Obtaining Your First Refresh Token

Your first refresh token can be generated from the **bank app Settings page**. Follow these steps:

1. Log in to the ORO Bank application
2. Navigate to **Settings**
3. Go to the **API Access** or **Developer Settings** section
4. Generate a new refresh token
5. **Save this token securely** - you'll need it to obtain access tokens

> **Warning:** Keep your refresh token secure. Anyone with access to your refresh token can authenticate as you.

## Authentication Flow

The ORO Bank API uses a two-token system for authentication:

## Using the Refresh Token

To get an access token, call the **[Refresh access token](/orobank/doc/oro-bank-api/operation/operation-refreshtoken)** endpoint (`POST /sessions/tokens`):

```bash
curl -X POST https://auth.bank.place/sessions/tokens \
  -H "Authorization: Bearer YOUR_REFRESH_TOKEN"
```

**Response:**

```json
{
  "accessToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": {
    "id": 25441,
    "value": "f3450c8c-718c-423d-8af0-d00d94c895ea",
    "createdAt": "2025-10-12T02:06:05.382028475Z",
    "updatedAt": "2025-10-12T02:06:05.382028647Z",
    "expiredAt": "2025-10-26T02:06:05.382011477Z"
  }
}
```

## Important: Refresh Token Rotation

> **Critical:** When a new refresh token is generated, **the previous one is immediately invalidated**.

This means:

1. Each call to `POST /sessions/tokens` returns a **new refresh token**
2. The **old refresh token becomes invalid** and cannot be reused
3. **You must persist the new refresh token** in your system for future requests

## Best Practices

1. **Store Refresh Tokens Securely**

   - Use environment variables or a secure secret management system
   - Never commit refresh tokens to version control
   - Encrypt refresh tokens at rest

2. **Handle Token Rotation**

   - Always update your stored refresh token after each refresh
   - Implement proper database/storage updates in your token refresh logic

3. **Error Handling**
   - Handle 401 errors by refreshing your access token
   - If refresh fails, your refresh token may have expired - generate a new one from Settings

## Quick Reference

| Token Type    | Lifespan   | Used For                  | Endpoint                                                                            |
| ------------- | ---------- | ------------------------- | ----------------------------------------------------------------------------------- |
| Access Token  | ~5 minutes | API requests              | All API endpoints                                                                   |
| Refresh Token | 3 hours    | Getting new access tokens | [POST /sessions/tokens](/orobank/doc/oro-bank-api/operation/operation-refreshtoken) |

See the [Refresh access token](/orobank/doc/oro-bank-api/operation/operation-refreshtoken) endpoint documentation for complete API details.