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

# Authentication

Authenticate with the Findity APIs using OAuth 2.0 to obtain access tokens for all endpoints.

## Obtain your API credentials

1. **Request login credentials** to [Findity's Admin Portal](https://stage-expense.findity.com/) by contacting your project manager or [Findity's support](mailto:support@findity.com).
2. Activate **API connectivity** on the **Marketplace** page.
3. **Obtain API credentials** — you need a `client_id` and `client_secret` to authenticate. To obtain these, you log into your Findity Admin Portal using your login credentials and navigate to Administrators → API keys.

> [!WARNING]
>
> Keep your client secret confidential. Never expose it in client-side code or public repositories.

## OAuth 2.0 overview

The Findity APIs use the [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) framework. Exchange your client credentials for an access token, then include that token in the `Authorization` header of every API request.

The API key has organization-level scope by default. For Partner or Client Application access, contact [support](https://developer.findity.com/docs/welcome.md#reach-out-to-us).

![OAuth flow](https://mintcdn.com/findity-docs/fTsgC-3N_Y6D9oSZ/images/docs/a36ad8f-Oauth_flow_1.png?fit=max\&auto=format\&n=fTsgC-3N_Y6D9oSZ\&q=85\&s=6213d12ac72c4e8b4a09e62352298559)

OAuth flow

## Request an access token

Exchange your client credentials for an access token using the client credentials grant type.

```bash theme={"system"}
curl -X POST "https://expense.findity.com/api/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"
```

The response includes an access token, token type, expiration time (in seconds), and a refresh token:

```json theme={"system"}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}
```

Include the access token in subsequent API requests using the `Authorization` header:

```bash theme={"system"}
curl -X GET "https://expense.findity.com/api/v1/..." \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

When the token expires, request a new one using either your client credentials or the refresh token.

## Refresh an access token

Make a POST request to the token endpoint with `grant_type=refresh_token`. Include the refresh token and client ID. A refresh token can only be used once — each response returns a new refresh token.

```bash theme={"system"}
curl -X POST "https://expense.findity.com/api/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&client_id=CLIENT_ID&refresh_token=REFRESH_TOKEN"
```

The response contains a new access token and a new refresh token, in the same format as the initial token request.

## Request a user access token

To act as a specific user (employee) — for example, when building against the Expense API — you need a user-scoped access token. This is a two-step process:

> [!WARNING]
>
> Requesting a user access token requires special administrator permissions. Contact your Findity contact person or
> reach out to [support](https://developer.findity.com/docs/welcome.md#reach-out-to-us) to get this permission granted.

**Step 1:** Request an authorization code by sending the user's ID (person ID or ExternalSourceID) to the authorization grant endpoint. This requires a valid organization-level access token.

```bash theme={"system"}
curl --request POST \
     --url https://stage-expense.findity.com/api/oauth/authorization-grant \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ACCESS_TOKEN' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data user_id="8ab28c3e6f8023c3016f8046be110102"
```

The response contains an authorization code:

```json theme={"system"}
{
  "code": "YOUR_AUTHORIZATION_CODE"
}
```

**Step 2:** Exchange the authorization code for a user access token.

```bash theme={"system"}
curl --request POST \
     --url https://stage-expense.findity.com/api/oauth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=authorization_code \
     --data code="YOUR_AUTHORIZATION_CODE"
```

![](https://mintcdn.com/findity-docs/fTsgC-3N_Y6D9oSZ/images/docs/c767bc4-Oauth_flow_2_behalf_of_a_user.png?fit=max\&auto=format\&n=fTsgC-3N_Y6D9oSZ\&q=85\&s=f648f186015d63be8a6faf1e903290de)

> [!NOTE]
>
> We support long-lived access tokens, but we recommend using the OAuth process described above for a more secure
> implementation.