# Authentication

## Overview

All Almond APIs are secured using **OAuth 2.0** with the **Client Credentials** grant type. This industry-standard authentication mechanism ensures secure, token-based access to API resources without exposing sensitive credentials in every request.

## Authentication Flow

**1. Obtain Access Token**

Authenticate using your Client ID and Client Secret to receive a time-limited access token from the Almond Authorization Server.

**2.  Include Token in API Requests**

Include the access token as a Bearer token in the Authorization header for all API requests (except the token endpoint itself).

**3. Refresh When Expired**

Monitor token expiration and request a new token before it expires to maintain uninterrupted API access.

## Scopes

Almond implements **scope-based access control** to enforce the principle of least privilege. Each scope grants access to a specific subset of API resources.

| Scope | Access Level | Description |
|  --- | --- | --- |
| `settlements` | Settlement APIs | Grants access to all settlement-related operations, including initiation, querying, and management of cross-border settlements |
| `payouts` | Payout APIs | Grants access to all payout-related operations, including payout initiation, process,  status queries, cancellation, and search |
| `member` | Member APIs | Grants access to financial institution management and configuration endpoints |


## Token API Reference

### Request Access Token

**Endpoint**
`POST /oauth2/token`

**Authentication**
HTTP Basic Authentication
(Base64-encoded `client_id:client_secret`)

**Content-Type**
`application/x-www-form-urlencoded`

### Request Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `grant_type` | string | Yes | Must be `client_credentials` |
| `scope` | string | Yes | Space-separated list of requested scopes (e.g., `member transactions`) |


### Example Request

**cURL**


```bash
curl -X POST https://api.almond.com/oauth2/token \
  -H "Authorization: Basic <Base64(client_id:client_secret)>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=member payouts"
```

### Response


```json
{
  "access_token": "X1PTWZre0fnW72l263yrhAWB2FDwx3tg",
  "Scope": "member payouts",  
  "token_type": "Bearer",
  "expires_in": 300
}
```