# Authentication

Use this guide to set the minimum security contract for every ConnectPSP request before you move on to Cash-In or Cash-Out flows.

## Request identity model

All API requests require two forms of identification:

| Header | Description | When Required |
|  --- | --- | --- |
| `Authorization` | `Bearer <jwt_token>` | All endpoints (except `POST /auth/token`) |
| `ApplicationToken` | Fixed GUID identifying your integration | All endpoints (except `POST /auth/token`) |
| `DigitalSignature` | HMAC-SHA256 hash — see below | Sensitive operations: Cash-Out, Rebalance |


## Recommended sequence

1. Generate a JWT with `POST /auth/token`
2. Send `Authorization` + `ApplicationToken` on authenticated endpoints
3. Add `DigitalSignature` only on sensitive operations such as Cash-Out and Rebalance
4. Add `X-Idempotency-Key` on mutation endpoints to make retries safe


## Step 1 — Obtain a JWT Token

Call `POST /auth/token` with the `clientId` and `clientSecret` provided by ConnectPSP during onboarding.


```bash
curl -X POST https://api.homologacao.connectpsp.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'
```

**Response:**


```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "issuedAt": "2026-03-10T14:00:00Z"
}
```

| Field | Meaning |
|  --- | --- |
| `accessToken` | JWT used in the `Authorization` header |
| `tokenType` | Header scheme, expected to be `Bearer` |
| `expiresIn` | Token lifetime in seconds |
| `issuedAt` | Token issuance timestamp |


> ⏱️ Tokens expire in **1 hour** (`expiresIn: 3600`). Implement refresh logic in your application to re-authenticate before the token expires.


## Step 2 — Send the minimum authenticated request

Send the `accessToken` in all subsequent requests:


```bash
curl https://api.homologacao.connectpsp.com/cash-in/US7B1JQ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "ApplicationToken: f47ac10b-58cc-4372-a567-0e02b2c3d479"
```

This is the baseline header pair you should expect on almost every request outside the token endpoint.

## Step 3 — Digital Signature (Sensitive Operations)

Cash-Out (`POST /cash-out`) and Rebalance (`POST /account/rebalance`) require an additional `DigitalSignature` header to guarantee integrity and authorization.

### How to Compute

The Digital Signature is an **HMAC-SHA256** hash of your **JWT token concatenated with your CryptoToken** (a separate fixed secret provided during onboarding, different from `clientSecret`).


```
DigitalSignature = HMAC_SHA256(key: cryptoToken, message: jwtToken)
                   → returned as a lowercase hexadecimal string
```

### Examples

**Node.js:**


```javascript
const crypto = require('crypto');

function computeSignature(jwtToken, cryptoToken) {
  return crypto
    .createHmac('sha256', cryptoToken)
    .update(jwtToken)
    .digest('hex');
}

const signature = computeSignature(accessToken, 'your-crypto-token-here');
// Use in: -H "DigitalSignature: <signature>"
```

**Python:**


```python
import hmac, hashlib

def compute_signature(jwt_token: str, crypto_token: str) -> str:
    return hmac.new(
        crypto_token.encode(),
        jwt_token.encode(),
        hashlib.sha256
    ).hexdigest()
```

**cURL (full example for Cash-Out):**


```bash
SIGNATURE=$(echo -n "$JWT_TOKEN" | openssl dgst -sha256 -hmac "$CRYPTO_TOKEN" | awk '{print $2}')

curl -X POST https://api.homologacao.connectpsp.com/cash-out \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "ApplicationToken: $APP_TOKEN" \
  -H "DigitalSignature: $SIGNATURE" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

> 🔑 **Never expose your `cryptoToken` or `clientSecret` in client-side code or public repositories.**


## Idempotency

For `POST /cash-in` and `POST /cash-out`, always send an `X-Idempotency-Key` header set to a new UUID v4.

If a network failure causes you to retry the same request, sending the same `X-Idempotency-Key` guarantees you receive the original response without creating a duplicate transaction.


```bash
# Generate a new UUID for each request
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

## Related guides

- [Initial Setup](/tutorials/initial-setup) — onboarding baseline and environment setup
- [Webhooks](/guides/webhooks) — async confirmation flow after authenticated requests
- [Error Handling](/guides/error-handling) — what to do when auth or signature validation fails