# Authentication (/docs/direct-debit/authentication)

The Precium API uses OAuth 2.0 Client Credentials Flow for authentication.

## Overview [#overview]

All API requests must include a valid Bearer token in the Authorization header. Tokens are obtained by making a POST request to the authentication endpoint with your client credentials.

## Obtaining an Access Token [#obtaining-an-access-token]

### Endpoint [#endpoint]

| Environment | URL |
|---|---|
| Sandbox | `https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token` |
| Production | `https://prod-payce.auth.eu-west-1.amazoncognito.com/oauth2/token` |

### Request [#request]

```html
POST /oauth2/token HTTP/1.1
Host: dev-payce.auth.eu-west-1.amazoncognito.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_ENCODED_CREDENTIALS

grant_type=client_credentials
```

### cURL Example [#curl-example]

```bash
curl -X POST https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"
```

### Parameters [#parameters]

| Parameter | Type | Required | Description |
|---|---|---|---|
| `grant_type` | string | Yes | Must be `client_credentials` |

### Response [#response]

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

| Field | Type | Description |
|---|---|---|
| `access_token` | string | The Bearer token to use in API requests |
| `expires_in` | integer | Token validity in seconds (86400 = 24 hours) |
| `token_type` | string | Always `Bearer` |

## Using the Access Token [#using-the-access-token]

Include the token in the `Authorization` header for all API requests:

```text
GET /v2/merchantprofile/ HTTP/1.1
Host: dev.api.revio.co.za
Authorization: Bearer eyJraWQiOiJYMHJhS...
Content-Type: application/json
```

### cURL Example [#curl-example-1]

```bash
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
  -H "Authorization: Bearer eyJraWQiOiJYMHJhS..." \
  -H "Content-Type: application/json"
```

## Token Management Best Practices [#token-management-best-practices]

### Token Expiry [#token-expiry]

Access tokens expire every **24 hours**. Implement token refresh logic in your application:

```jsx
// Pseudocode example
function getValidToken() {
  if (token && !isExpired(token)) {
    return token;
  }
  return refreshToken();
}
```

### Security Guidelines [#security-guidelines]

1. **Store tokens securely**: Access tokens should be stored in an encrypted format at rest if stored server-side
2. **Limit access**: The number of employees with access to tokens should be kept to a need-to-know basis
3. **Report breaches immediately**: If a token breach is detected, contact Precium immediately so affected tokens can be revoked
4. **Never expose in client-side code**: Do not include credentials or tokens in client-side JavaScript or mobile apps
5. **Use HTTPS**: All API requests must be made over HTTPS

### Error Handling [#error-handling]

If your token is invalid or expired, the API will return:

```json
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

When you receive a 401 response, request a new access token before retrying the request.

## Test Credentials [#test-credentials]

To request sandbox credentials, contact the Precium support team at support@precium.com

Your sandbox credentials will include:

- `client_id` (username)
- `client_secret` (password)

## Production Credentials [#production-credentials]

The production base URL is `https://api.revio.co.za/`. Your production `client_id` and `client_secret` are issued at go-live. Contact your Precium account manager to initiate the onboarding process.

## API Endpoints [#api-endpoints]

After authentication, use the following base URLs:

| Environment | Base URL |
|---|---|
| Sandbox | `https://dev.api.revio.co.za/` |
| Production | `https://api.revio.co.za/` |

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

| Error | Cause | Solution |
|---|---|---|
| `401 Unauthorized` | Invalid or expired token | Request a new access token |
| `403 Forbidden` | Insufficient permissions | Contact support to verify account setup |
| `invalid_client` | Incorrect credentials | Verify your client_id and client_secret |
| `unsupported_grant_type` | Wrong grant_type value | Ensure `grant_type=client_credentials` |

### Testing Your Token [#testing-your-token]

Verify your token is working by calling the merchant profile endpoint:

```bash
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
  -H "Authorization: Bearer YOUR_TOKEN"
```

A successful response confirms your authentication is configured correctly.