> For the complete documentation index, see [llms.txt](https://developer.fraudcheck.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fraudcheck.co.za/commercial-service/authentication.md).

# Authentication

The Fraudcheck Commercial Service API uses JWT bearer tokens for authentication. Tokens are obtained from a dedicated authentication endpoint separate from the commercial service base URL.

## How it works

1. POST your credentials to `/auth/login` → receive an `access_token`
2. Include the token on every API request as `Authorization: Bearer {access_token}`
3. Tokens expire after **60 minutes** - request a new one when you receive a `401`

## Token endpoint

```http
POST https://commercial-service-api.fraudcheckonline.co.za/auth/login
```

### Request

```json
{
  "email": "you@example.com",
  "password": "yourpassword"
}
```

### Response

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

## Using the token

Add the token to the `Authorization` header of every commercial service request:

```http
Authorization: Bearer {your_access_token}
```

## Code examples

{% tabs %}
{% tab title="cURL" %}

```bash
AUTH_URL="https://commercial-service-api.fraudcheckonline.co.za/auth/login"

# Get token
ACCESS_TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}' \
  | jq -r '.access_token')

echo "Token: $ACCESS_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

AUTH_URL = "https://commercial-service-api.fraudcheckonline.co.za/auth/login"

response = requests.post(
    AUTH_URL,
    json={"email": "you@example.com", "password": "yourpassword"},
)
access_token = response.json()["access_token"]
```

{% endtab %}

{% tab title="JavaScript (Node.js)" %}

```javascript
const AUTH_URL = "https://commercial-service-api.fraudcheckonline.co.za/auth/login";

const response = await fetch(AUTH_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", password: "yourpassword" }),
});
const { access_token: accessToken } = await response.json();
```

{% endtab %}
{% endtabs %}

## Errors

| HTTP | Meaning                                       | Action                                |
| ---- | --------------------------------------------- | ------------------------------------- |
| 401  | Token missing, expired, or invalid            | Request a new token via `/auth/login` |
| 403  | Account lacks access to the requested service | Contact your account manager          |