# Authentication Token

# How to Get an API Token

---

## Overview

Our API uses **OAuth 2.0 Client Credentials** flow for secure server-to-server authentication. This guide will walk you through obtaining and using your API token to access our Back Office API.

> ** Authentication Method**
> 
> We use OAuth 2.0 Client Credentials flow - perfect for server-to-server authentication where no user interaction is required.

---

## ⚡ Quick Start

Follow these simple steps to get your API token:

> ** Step-by-Step Process**
> 1. **Obtain** your `client_id` and `client_secret` from the Lone Wolf Technologies integrations team
> 2. **Make** a POST request to our token endpoint with your credentials  
> 3. **Receive** an access token valid for 24 hours
> 4. **Include** the token in the Authorization header of all API requests

### Authentication Flow

```
Your Application → Token Endpoint → Access Token → API Resources
```

---

## Token Endpoint

**POST** `https://gateway.lwolf.com/oauth/token`

### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| **grant_type** | `string` | Must be `"client_credentials"` |
| **client_id** | `string` | Your application's client ID from Lone Wolf Technologies |
| **client_secret** | `string` | Your application's client secret from Lone Wolf Technologies |
| **audience** | `string` | Must be `"https://api.lwolf.com"` |

### Optional Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| **lwt_client_id** | `string` | Specific customer instance ID for multi-tenant applications |

---

## 💻 Implementation Examples

### cURL
```bash
curl -X POST https://gateway.lwolf.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id_here",
    "client_secret": "your_client_secret_here",
    "audience": "https://api.lwolf.com"
  }'
```

### JavaScript
```javascript
const response = await fetch('https://gateway.lwolf.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'your_client_id_here',
    client_secret: 'your_client_secret_here',
    audience: 'https://api.lwolf.com'
  })
});

const data = await response.json();
const accessToken = data.access_token;
```

### Python
```python
import requests

response = requests.post(
    'https://gateway.lwolf.com/oauth/token',
    json={
        'grant_type': 'client_credentials',
        'client_id': 'your_client_id_here',
        'client_secret': 'your_client_secret_here',
        'audience': 'https://api.lwolf.com'
    }
)

data = response.json()
access_token = data['access_token']
```

---

## Successful Response

When your request is successful, you'll receive:

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

> ** Token Validity**
> 
> Tokens are valid for **24 hours (86400 seconds)**

---

## Using Your Token

Include your access token in the `Authorization` header of all API requests:

```bash
curl -X GET https://backoffice.api.dev.lwolf.com/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"
```

---

## Security Best Practices

> **Important Security Guidelines**
> - **Never** expose your `client_secret` in client-side code or public repositories
> - **Store** credentials securely using environment variables or key management systems
> - **Implement** token refresh logic before the 24-hour expiration
> - **Use** HTTPS for all API communications

---

## Token Management

### Refresh Strategy
- Cache the token and its expiration time
- Request a new token before the current one expires (at ~90% of lifetime)
- Implement retry logic with exponential backoff
- Handle refresh failures gracefully

---

## Common Errors

| Error Code | Description | Solution |
|------------|-------------|----------|
| `401 Unauthorized` | Invalid credentials | Verify your `client_id` and `client_secret` |
| `400 Bad Request` | Malformed request | Check all required parameters are included |
| `403 Forbidden` | Token expired/invalid | Request a new access token |
| `429 Too Many Requests` | Rate limit exceeded | Implement exponential backoff |

---

## Need Help?

> **Contact Support**
> 
> Having trouble with authentication? Contact the **Lone Wolf Technologies integrations team** or reach out to:
> 
> **[developersupport@lwolf.com](mailto:developersupport@lwolf.com)**

---

<div align="center">

**Ready to authenticate?**

*Your token is the key to unlocking our API's full potential.*

</div>