> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Connect to Inventi Payment Platform and make your first API call.

# Authentication

Connect to Inventi Payment Platform to access SEPA, SEPA Direct Debit, and SWIFT payments through CSM.

<Info>
  **What you'll need:**

  * API credentials (client ID and secret) from your Inventi representative
  * Your Tenant ID from the Configuration Matrix
  * Whitelisted IP addresses for your servers
</Info>

## Before You Start

Before making API calls, ensure your environment is ready:

<Steps>
  <Step title="Receive your credentials">
    Your Inventi representative will provide your Tenant ID and initial API credentials. These are specific to your institution.
  </Step>

  <Step title="Whitelist your IPs">
    Contact `connectors-support@inventi.lt` to register your server IP addresses. API calls from non-whitelisted IPs will be rejected.
  </Step>

  <Step title="Access the sandbox">
    Start in the sandbox environment to build and test your integration before going live.
  </Step>
</Steps>

## Environments

| Environment | Auth URL                    | API URL                        |
| ----------- | --------------------------- | ------------------------------ |
| Sandbox     | `auth.sandbox.finventi.com` | `api.pgw-sandbox.finventi.com` |
| Production  | `auth.finventi.com`         | `api.pgw.finventi.com`         |

<Warning>
  Always develop and test in sandbox first. Production credentials are issued only after successful sandbox validation.
</Warning>

***

## Overview

The Inventi Payment Platform API uses OAuth 2.0 for authentication. To access the API, you need to obtain a bearer token from the authorization server and include it in all API requests.

<Note>
  **IP Whitelisting Required**: Before you can access the API, your IP address must be whitelisted. Contact `connectors-support@inventi.lt` to register your IP addresses.
</Note>

## Obtaining a Bearer Token

To authenticate with the API, you need to obtain a bearer token using the OAuth 2.0 client credentials flow.

### Token Request

Use the following cURL command to obtain a bearer token:

```bash theme={null}
curl -X POST \
  --location 'https://auth.sandbox.finventi.com/realms/<client-name>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=api-sepa-gateway-client' \
  --data-urlencode 'client_secret=<client-secret>'
```

### Parameters

<ParamField body="grant_type" type="string" required>
  Must be set to `client_credentials`
</ParamField>

<ParamField body="client_id" type="string" required>
  Always use `api-sepa-gateway-client`
</ParamField>

<ParamField body="client_secret" type="string" required>
  Your client secret obtained from the SEPA Dashboard UI
</ParamField>

### Variables to Replace

* **`<client-name>`**: Your TenantID assigned by the Inventi team during initial configuration. This can be found in the Configuration Matrix shared with your representative.
* **`<client-secret>`**: Your API client secret, available in the Inventi Payment Platform under API Credentials

### Token Response

A successful response will include your access token:

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...",
  "expires_in": 2700,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "profile email"
}
```

<Warning>
  The bearer token is valid for **45 minutes**. After expiration, you'll need to request a new token.
</Warning>

## Using the Bearer Token

Include the bearer token in the `Authorization` header of all API requests with the `Bearer` prefix.

### Authorization Header Format

```
Authorization: Bearer <bearer-token>
```

### Example API Request

Here's an example of using the bearer token to create a SEPA payment:

```bash theme={null}
curl --location --request POST 'https://api.pgw-sandbox.finventi.com/gateway/createSepaPmt' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000' \
  --data '{
    "payment": {
      "amount": 100.50,
      "currency": "EUR",
      "creditorIban": "LT123456789012345678",
      "debtorIban": "LT987654321098765432"
    }
  }'
```

## Authentication Flow Diagram

```mermaid actions={true} theme={null}
sequenceDiagram
    participant Client
    participant Auth as Auth Server
    participant API as SEPA API

    Client->>Auth: POST /token<br/>client_credentials
    Auth->>Client: Bearer token<br/>(valid 45 min)
    Client->>API: API Request<br/>+ Bearer token
    API->>Client: API Response

    Note over Client,Auth: After 45 minutes
    Client->>Auth: POST /token<br/>(new token request)
    Auth->>Client: New Bearer token
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Token Management" icon="key">
    * Cache tokens until they expire
    * Implement token refresh logic before expiration
    * Never expose tokens in client-side code
  </Card>

  <Card title="Security" icon="shield">
    * Store client secrets securely
    * Use environment variables for credentials
    * Rotate client secrets regularly
  </Card>
</CardGroup>

## Common Issues

### Invalid Client Credentials

If you receive an authentication error, verify:

* Your client secret is correct and hasn't been rotated
* The TenantID (client-name) is correctly specified
* Your IP address is whitelisted

### Expired Token

If you receive a 401 Unauthorized error:

* Check if 45 minutes have passed since token generation
* Request a new bearer token
* Update your application's token cache

## What's Next?

You're now connected to Inventi. The next step is to set up accounts for your customers:

<CardGroup cols={2}>
  <Card title="Create Customer Accounts" icon="users" href="/payments/accounts-management">
    Set up IBANs for your customers to send and receive payments
  </Card>

  <Card title="Send Your First Payment" icon="paper-plane" href="/payments/outgoing-sepa-payment">
    Create a SEPA payment in the sandbox
  </Card>
</CardGroup>