# Authentication Guide

### Two Sets of Credentials

Remember, Congruit maintains two environments:

- Sandbox
- Production


Your Organization/company ID, Portfolio IDs, and Explans are synced across **both** environments.

However, your credentials remain separate. Sandbox credentials will not work in Production, and vice versa.

Your workhorse API calls (calling endpoints like `evaluation` and `ach_transactions`) require a short-lived (24 hours) bearer token in the request header. Bearer tokens are fetched from the `tokens` endpoint using your `ClientID` and `ClientSecret`.

We will supply your Sandbox credentials at the begining of the onboarding process, and your Production credentials after approval of your onboarding success.

#### OAuth Flow

Congruit uses [OAuth 2.0](https://oauth.net/2/) workflow for access/authentication management using bearer tokens (refresh tokens are not used).

Call our `tokens` endpoint to fetch a bearer token. That bearer token can then be used to authenticate your call to our workhorse API endpoints such as `evaluation`.

Bearer tokens are only valid for a period of time; after that time you need to call for a new bearer token.

1. **Fetch Bearer Token**

```bash
curl --request POST https://api.congruitcredit.com/tokens \
     --header "Content-Type: application/json" \
     --data '{"token": \
     {"client_id":"Tl0MJLZviPysiz6saxx7TKivMCoVJcDZ", \
     "client_secret":"uTWAMB7M4kxxuvVcBlL__ynXGSoTCHkbZelLRNG6vy1bMJxXxzOSQCrxUB8_G3e7"} \
     }'
```

```json
{"token":"eyJhbGciOiJSUzI1NixxInR5cCI6IkpXVCIsImtpZCI6IkJ4Wnl3MUZyWF84LUxLMWlLTFJ0aCJ9.eyJodHRwczovL2Rldi12YW5nL2FwaS92MS9vcmdhbml6YXRpb25faWQiOiJPUkcjMDE5OGEzZGUtOWMxNS03ZjlkLTkwMDktNzhmOGNkMTlhYzhlIiwiaXNzIjoiaHR0cHM6Ly9kZXZlbG9wbWVudC1jb25ncnVpdGNyZWRpdC51cy5hdXRoMC5jb20vIiwic3ViIjoidE92RmJNWVp1enZBMWhzQkI4bm1BNm4xb0ZXcm9PNmtAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vZGV2LXZhbmcvYXBpL3YxLyIsImlhdCI6MTc1NTEwNzI3OCwiZXhwIjoxNzU1MTkzNjc4LCJndHkiOiJ1bGllbnQtY3JlZGVudGlhbHMiLCJhenAiOiJ0T3ZGYk1ZWnV6dkExaHNCQjhubUE2bjFvRldyb082ayJ9.Z4CqoXZAE52c2jRiRGnSazl8s-D84cU1ltSl_WZlmKF8BrqtdXQNzoMKK-xH2XNKhxojGSEFzBGaJ9gEdjyrQ-Pzum0jzmrs7Nnppr5f32gXWREHe28fH7pHlNV22dQVaTIrDSWAu-dNPCTr1heHnaDNNHFB0TBJzNMYULxiHw7ygu0eMsnd5_QHeU6bQNwfSoQ1N-4gJQe6IctfZ_UR_WBG27fMtiNbxNF8_Su6Hvb7cFml8uSUBH1HJqRLShyPhqXP18LJqOKEdHbF3FQQIofPe-F6gy29eo07fI69VYcNM6k0Pg5m9wGSEEAtKRndI0a89CKJjuPjiWRlDCJFvg",
  "expires_at":1755100800,
  "token_type":"Bearer"}
```
2. **Use Bearer Token**

```bash
curl --header "Authorization: Bearer BEARER_TOKEN" \
     https://api.congruitcredit.com/v1/[endpoint] \
     --data {payload}
```
3. **Refresh Bearer Token**
Each bearer token expires in 24 hours, so your application should:
  - cache the bearer token locally so that you avoid the overhead latency of the token call for your workhorse API calls.
  - set your cache entry to expire at the `expires_at` epoch time in the fetch response.
  - as your cache expires, fetch a new bearer token to cache locally and use.


Note that this process does not use a refresh token like some other refresh patterns.

Do you absolutely need to cache the bearer token? No, you could request it prior to every API call but that adds latency. No matter how many times you call Congruit for a bearer token, you will receive the *same* token in response until the token expires.

## Security Best Practices

### API Token Security

- **Store securely**: Never hardcode tokens or secrets in your application.
- **Environment variables**: Use environment variables for secrets.
- **Monitor usage**: Watch for unusual activity.


### Permitted IPs

For enhanced security, you must add your development, test, staging, and production IP addresses to our allowlist. Please supply these to us during onboarding.

### TLS Version

We require TLS 1.3 for all API connections. Only these ciphers are supported (AWS Best Practice):

- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256


## Error Handling

### Authentication Errors

| Error Code | Description | Solution |
|  --- | --- | --- |
| `401` | Invalid client credentials | Check your Client ID and Client Secret with your Congruit Account Manager |
| `429` | Rate limit exceeded | Wait and retry |


### Example Error Response

```json
{"error": "unauthorized"}
```

## Testing Authentication

### Health Check

Check that the system is up and responding:

```bash
curl  --request POST https://api.congruitcredit.com/tokens/health_check
```

```
{"I'm alive at 2025-06-04 23:15:04 CHECK THIS"}
```

### Token Validation

Validate an OAuth token is working (unexpired):

```bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
     https://api.yourcompany.com/tokens/validate
```

```json
{
  "valid": true,
  "message": "The token is valid."
}
```

If the bearer token has expired, then you will receive a `401` HTTP error. Simply request a new bearer token.

### Getting Help

**Support**: Email [support@congruitcredit.com](mailto:support@congruitcredit.com)