> ## 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 VoP API using OAuth 2.0.

## Overview

The Inventi VoP 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' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=api-vop-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-vop-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-vop-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's an example of using the bearer token to import VoP account data:

```bash theme={null}
curl --location --request POST 'https://api.vop-sandbox.finventi.com/api/v1/accounts' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...' \
--header 'Content-Type: application/json' \
--data '{
  "iban": "LT123456789012345678",
  "account_holder_name": "John Doe"
}'
```

## 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 VoP services:

<CardGroup cols={3}>
  <Card title="Testing Guide" icon="flask" href="/vop/testing-guide">
    Complete mandatory test scenarios before production
  </Card>

  <Card title="Verify Account Holder" icon="shield-check" href="/vop/api/verification/verify-account-holder">
    Verify IBAN and account holder details in real-time
  </Card>

  <Card title="Manage VoP Accounts" icon="database" href="/vop/api/account-management/batch-import-of-account-entries">
    Import and manage account verification data
  </Card>
</CardGroup>