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 endpoint (POST /sessions/tokens):

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

Response:

{
  "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

1. Handle Token Rotation

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

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

See the Refresh access token endpoint documentation for complete API details.