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

# Getting started

## Prerequisites

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 the Partner view, then in the left menu Administrators, then API keys.

## Environments

Findity provides two environments. Use the stage environment during development and testing, then switch to production when you're ready to go live.

| Environment | Base URL | Purpose |
| - | - | :- |
| Stage | `https://stage-api.findity.com/api/v1/admin` | Development and testing. Safe to create test organisations and experiment with configurations. Data is periodically reset. |
| Production | `https://expense.findity.com/api/v1/admin` | Live environment with real customer data. Use only after your integration has been verified in stage. |

> [!WARNING]
>
> All examples in this guide use the **stage** base URL. Replace `stage-api.findity.com` with `api.findity.com` when moving to production.

## Step 1: Authenticate

Every integration starts with obtaining an access token. Send a `POST` request to the OAuth token endpoint using the `client_credentials` grant type:

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

A successful response returns a Bearer token:

> **Example response**
>
> ```json Response theme={"system"}
> {
>   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
>   "token_type": "Bearer",
>   "expires_in": 3600
> }
> ```

Include this token in the `Authorization` header for all subsequent API requests:

```bash theme={"system"}
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

> [!WARNING]
>
> Tokens expire after the duration specified in `expires_in` (in seconds). Your integration should handle token refresh by requesting a new token before the current one expires.

## Step 2: Choose your integration path

After authentication, continue with one or more of the APIs below. We recommend integrating them in this order:

> **[Admin API](/docs/admin-api)**
>
> **Start here.** Provision and manage organizations, dimensions, charts of accounts, users, and approval structures.

> **[Expense API](#)**
>
> Embed expense management directly in your application. Give your users a native expense reporting experience.

> **[Connect API](#)**
>
> Export expense data and process accounting vouchers for ERP and accounting system integrations.

### Recommended integration order

Most partners begin with the **Admin API** to set up the organizational foundation and provisioning, then add the **Expense API** when they want to embed expense management into their product, and integrate the **Connect API** for accounting exports. Each API can be integrated standalone, but following this order ensures each layer builds on the previous one.

| Order | API | What it covers |
| - | - | - |
| 1 | **Admin API** | Provisioning of organizations, dimensions, charts of accounts, users, approval structures, and more. |
| 2 | **Expense API** | Embedded expense management: Expense creation, reporting, and more. |
| 3 | **Connect API** | Data exports, card transactions, and accounting integrations. |