# Authentication

Authentication is the first and most important step when using the **Theropay API**.
It ensures that your requests are secure and that only authorized clients can access merchant data.

## Security Model: OAuth 2.0 (Client Credentials Flow)

> Theropay’s API uses the **OAuth 2.0 Client Credentials** flow for authentication.
Instead of a static API key, you use a **Client ID** and **Client Secret** to obtain a **short-lived Access Token**.
That token is then used to authenticate all your API requests.


### Credentials Overview

| Field | Description |
|  --- | --- |
| **Client ID** | Your public identifier for the application |
| **Client Secret** | Your private key used to authenticate your client |
| **Access Token** | A short-lived token you receive after authentication; used for API requests |


> ⚠️ **Keep your client secret safe!** Never expose it publicly or commit it to source control.


## Step 1: Generate an Access Token

To obtain an access token, make a `POST` request to the authentication endpoint:


```bash
curl -X POST "<AUTH_BASE_URL>/oauth/token" \
     -H "Content-Type: application/json" \
     -d '{
           "client_id": "YOUR_CLIENT_ID",
           "client_secret": "YOUR_CLIENT_SECRET",
           "grant_type": "client_credentials"
         }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Example Request (Fetching Payees)


```bash
curl -X GET "<API_BASE_URL>/v1/payees" \
     -H "Authorization: Bearer ACCESS_TOKEN_HERE" \
     -H "Content-Type: application/json"
```


```js
fetch('<API_BASE_URL>/v1/payees', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN_HERE',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));
```

### Token Expiry and Renewal

> Access tokens typically expire after a short period (for example, 1 hour).
When expired, repeat Step 1 to request a new token using your client credentials.
Always store tokens securely and refresh them as needed.


### Summary

Step	Action

> 1️⃣	Use your client_id and client_secret to obtain an access token
2️⃣	Include the token in every API request as a Bearer token
3️⃣	Replace placeholder URLs with actual environment URLs
4️⃣	Regenerate tokens when they expire