Authentication

Overview

Authentication in Open Banking involves two parties:

• TPP Authentication - Your application authenticates with our API using OAuth 2.0 client credentials
• Customer Authorization - The bank customer authorizes your application to access their data

OAuth 2.0 Flows

Authorization Code Flow

Used for accessing customer resources (accounts, transactions, payments). Requires customer authorization.

Client Credentials Flow

Used for TPP-to-bank operations that don't require customer context, such as creating consent requests.

curl -X POST "https://api.hamsterbank.ai/oauth/token" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=client_credentials" \\
  -d "scope=consents" \\
  -d "client_id={client_id}" \\
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \\
  -d "client_assertion={signed_jwt}"

FAPI 1.0 Advanced

We implement FAPI 1.0 Advanced security profile which includes:

Client Authentication

We support two methods for TPP authentication at the token endpoint:

private_key_jwt (Recommended)

Sign a JWT with your private key. The JWT must include:

{
  "iss": "{client_id}",
  "sub": "{client_id}",
  "aud": "https://api.hamsterbank.ai/oauth/token",
  "jti": "unique-id-12345",
  "exp": 1702512300,
  "iat": 1702512000
}

tls_client_auth

Authenticate using mutual TLS with a client certificate. The certificate must be issued by a trusted CA and match your registration.

Consent Management

Before accessing customer data, you must obtain their consent. There are three types of consents:

Creating a Consent

curl -X POST "https://api.hamsterbank.ai/consents/account-access" \\
  -H "Authorization: Bearer {client_credentials_token}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "permissions": [
      "ReadAccounts",
      "ReadBalances",
      "ReadTransactions"
    ],
    "expiration_date": "2024-03-15T00:00:00Z",
    "transaction_from_date": "2023-01-01T00:00:00Z"
  }'

Consent Permissions

• ReadAccounts - View account list and details
• ReadAccountsBasic - View basic account info only
• ReadBalances - View account balances
• ReadTransactions - View transaction history
• ReadTransactionsBasic - View basic transaction info
• ReadStandingOrders - View standing orders
• ReadDirectDebits - View direct debits
• ReadBeneficiaries - View saved payees

Token Lifecycle

Refreshing Tokens

curl -X POST "https://api.hamsterbank.ai/oauth/token" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=refresh_token" \\
  -d "refresh_token={refresh_token}" \\
  -d "client_id={client_id}" \\
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \\
  -d "client_assertion={signed_jwt}"

OAuth Endpoints

Security Best Practices

• Always use PKCE with authorization code flow
• Store tokens securely and never expose them to the browser
• Use short-lived access tokens and refresh them as needed
• Validate all tokens before trusting their claims
• Use state parameter to prevent CSRF attacks
• Implement proper token revocation when users disconnect