# Overview (/docs/api/platform-api-overview)



# Platform API [#platform-api]

The Lunch Flow Platform API lets you embed financial data into your own product. Register users, connect their bank accounts, and read their transaction, balance, and holdings data.

<Callout type="info">
  If you only need to access your own data, check out the simpler [Personal API](/docs/personal-api/overview).
</Callout>

## Base URL [#base-url]

```
https://lunchflow.app/api/platform/v1
```

## Authentication [#authentication]

| Scheme           | Credentials                   | Used for                                |
| ---------------- | ----------------------------- | --------------------------------------- |
| **Basic Auth**   | `client_id` : `client_secret` | Managing users (create, update, delete) |
| **Bearer Token** | `access_token`                | Accessing user data, portal sessions    |

Your `client_id` and `client_secret` come from the [Developer Dashboard](https://lunchflow.app/developer). The `access_token` is returned when you register a user or when a user completes the OAuth flow.

Refresh expired tokens via `POST /oauth/token` with `grant_type=refresh_token`.

## Two integration approaches [#two-integration-approaches]

You can choose for the end user to pay the subscription, or you can pay for their subscription. The integration process follows a very similar flow in both cases: Share a link with your end users to connect their banks, redirect to your website, and access data server-side. The only difference is whether users get a checkout form (when they're paying) or go directly to connect a number of bank accounts that you control (when you pay).

<Steps>
  <Step>
    ### Create an app [#create-an-app]

    Go to the [Developer Dashboard](https://lunchflow.app/developer) and create an app to get your `client_id` and `client_secret`. Add a redirect URI.
  </Step>

  <Step>
    ### Register a user [#register-a-user]

    Call `POST /users` with Basic Auth. You get back an `access_token` and `refresh_token`.

    ```bash
    curl -X POST https://lunchflow.app/api/platform/v1/users \
      -u "$CLIENT_ID:$CLIENT_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"email": "user@example.com"}'
    ```
  </Step>

  <Step>
    ### Connect bank via OAuth [#connect-bank-via-oauth]

    Redirect the user to the authorize endpoint. They sign in, connect their bank, and are redirected back with a `code`.

    ```
    GET https://lunchflow.app/api/platform/oauth/authorize
      ?client_id=$CLIENT_ID
      &redirect_uri=https://yourapp.com/callback
      &email=user@example.com
      &state=$RANDOM_STATE
    ```

    Exchange the code for tokens:

    ```bash
    curl -X POST https://lunchflow.app/api/platform/oauth/token \
      -H "Content-Type: application/json" \
      -d '{
        "grant_type": "authorization_code",
        "code": "$AUTH_CODE",
        "redirect_uri": "https://yourapp.com/callback",
        "client_id": "$CLIENT_ID",
        "client_secret": "$CLIENT_SECRET"
      }'
    ```
  </Step>

  <Step>
    ### Access data [#access-data]

    Once the user has linked their bank, read their accounts, transactions, balances, and holdings.

    ```bash
    curl https://lunchflow.app/api/platform/v1/accounts \
      -H "Authorization: Bearer $ACCESS_TOKEN"
    ```
  </Step>
</Steps>

## Refreshing tokens [#refreshing-tokens]

Access tokens expire after 1 hour. Use the refresh token to get a new pair:

```bash
curl -X POST https://lunchflow.app/api/platform/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "$REFRESH_TOKEN",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET"
  }'
```

<Callout type="info">
  For public (self-hosted) clients, omit the `client_secret`.
</Callout>

## Endpoints [#endpoints]

Browse the interactive reference for each endpoint in the **Users** and **Accounts** sections of the sidebar.

## Support [#support]

Questions or issues? Email [hello@lunchflow.app](mailto:hello@lunchflow.app).