> ## 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

> Learn how to authenticate with the Ledger API using OAuth 2.0.

## Overview

The Inventi Ledger 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>

## Auth server URLs

<Tabs>
  <Tab title="Production">
    ```
    https://auth.finventi.com
    ```
  </Tab>

  <Tab title="Test">
    ```
    https://auth.sandbox.finventi.com
    ```
  </Tab>
</Tabs>

## 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 '<auth-server-url>/realms/<client-name>/protocol/openid-connect/token' \
--user "client_id:client_secret" \
--data "grant_type=client_credentials"
```

### 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-ledger-client`
</ParamField>

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

### Variables to Replace

* **`<auth-server-url>`**: Use `https://auth.sandbox.finventi.com/` for TEST or `https://auth.finventi.com/` for PROD
* **`<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 SEPA Dashboard UI by navigating to **User Management** → **Clients** → **api-ledger-client** → **Credentials** → **Client Secret**

### 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

```bash theme={null}
Authorization: Bearer <bearer-token>
```

### Example API Request

Here is an example of using the bearer token to get an account:

```bash theme={null}
curl --location --request GET 'https://api.ledger-sandbox.finventi.com/accounts/{accountId}' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...'
```

<ParamField path="accountId" type="string" required>
  The unique identifier (UUID) of the account to retrieve. Example: `019bdb2a-960f-789d-8955-21720e6cdeed`
</ParamField>

## 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="IP Not Whitelisted">
    If you cannot connect to the API:

    * Verify your IP address is registered with Inventi
    * Contact `connectors-support@inventi.lt` to add your IP
    * Check for any network changes (VPN, proxy, etc.)
  </Accordion>
</AccordionGroup>

## Next Steps

Once authenticated, you can start using Ledger services:

<CardGroup cols={3}>
  <Card title="Create Party" icon="user" href="/ledger/api/parties/create-party">
    Create individual or organisation parties
  </Card>

  <Card title="Create Account" icon="wallet" href="/ledger/api/accounts/create-account">
    Create accounts for your parties
  </Card>

  <Card title="Initiate Payment" icon="money-bill-transfer" href="/ledger/api/payments/create-payment">
    Initiate SEPA payments
  </Card>
</CardGroup>