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

# Introduction

> How to authenticate with Cognito and call the (single) Finhost Client API across payments and crypto features.

<Note>
  This page focuses **only** on API integration.
</Note>

<Warning>
  **Client → Backend only.** These APIs are designed for **front‑end clients (web/mobile) calling your Finhost backend** using end‑user tokens from **Amazon Cognito**. They are **not** intended for backend‑to‑backend calls with client secrets.
</Warning>

## Overview

Finhost exposes a **single** REST surface called **Client API**. It includes traditional banking features (clients, companies, accounts, transfers, transactions) **and** optional **crypto‑exchange** features.

* All requests are **JSON** over HTTPS with **Bearer** auth.
* Crypto endpoints are namespaced under `/crypto-exchange` within the same base URL.

***

## Environments & Base URLs

> Your tenant uses customer‑scoped hostnames.

* **Dev**: `https://client-api.dev.{your-domain}.io`
* **Prod**: `https://client-api.{your-domain}.io`

Replace `{your-domain}` with your assigned tenant domain (e.g., `acmebank`). Keep these values in env vars:

```bash theme={null}
export CLIENT_API_BASE="https://client-api.dev.{your-domain}.io" # or prod
```

***

## Authentication (Cognito)

Finhost relies on **Amazon Cognito User Pools** for user authentication and token issuance.

### What you need

* **User Pool ID** and **Region**
* **Web App Client ID** (no client secret for public web/mobile apps)
* (Optional) **Hosted UI** domain if you use Cognito’s OAuth2/PKCE login

### How it works

1. Your web/mobile app authenticates the **end user** against Cognito:
   * **Hosted UI + PKCE** (recommended) *or* a library like **AWS Amplify Auth**.
2. Cognito returns short‑lived **JWTs**:
   * **ID token** (user identity claims)
   * **Access token** (authorization for APIs)
   * **Refresh token** (to renew tokens silently)
3. Your app calls Finhost **Client API** with the **Access token** in the header:

```bash theme={null}
Authorization: Bearer <access_token>
```

4. On expiry, renew tokens via the **refresh token** (Amplify or Hosted UI session) and retry.

<Info>
  Register your front‑end origins in CORS. Avoid storing tokens in `localStorage`; prefer memory or secure, httpOnly cookies where applicable.
</Info>

### Example — fetch profile (JS)

```ts theme={null}
const res = await fetch(`${CLIENT_API_BASE}/client`, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const me = await res.json();
```

### Example — cURL

```bash theme={null}
curl --request GET \
  --url "$CLIENT_API_BASE/client" \
  --header "Authorization: Bearer $TOKEN"
```

***

## Canonical integration flows

### A) Individual onboarding (KYC → account → bank details → payments)

1. **Initiate client** — `POST /client`
   ```bash theme={null}
   curl -X POST "$CLIENT_API_BASE/client" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "name": "John", "surname": "Doe", "nationality": "UKR",
       "birthday": "2017-07-21", "phone": "+380689873682"
     }'
   ```
2. **Accept contract (client)** — `POST /v2/clients/contract-accept`
   ```bash theme={null}
   curl -X POST "$CLIENT_API_BASE/v2/clients/contract-accept" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"contractId": "regularContract"}'
   ```
3. **Get KYC access token** — `GET /v1/kyc/access-token` (for Sumsub Web SDK)
   ```bash theme={null}
   curl -X GET "$CLIENT_API_BASE/v1/kyc/access-token" \
     -H "Authorization: Bearer $TOKEN"
   ```
4. **Create account** — `POST /v1/accounts`
   ```bash theme={null}
   curl -X POST "$CLIENT_API_BASE/v1/accounts" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"title":"Main EUR","currency":"EUR","companyId":"<uuid>","variantId":"<id>"}'
   ```
5. **Fetch bank details** — `GET /v1/ext-accounts/{extAccountId}`
   ```bash theme={null}
   curl -X GET "$CLIENT_API_BASE/v1/ext-accounts/<extAccountId>" \
     -H "Authorization: Bearer $TOKEN"
   ```
   <Warning>
     `GET /account/details/{account}` is deprecated. Use `/v1/ext-accounts/{extAccountId}` instead.
   </Warning>
6. **Initiate external transfer** — `POST /v2/transfer`
   ```bash theme={null}
   curl -X POST "$CLIENT_API_BASE/v2/transfer" \
     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{
       "amount":"42",
       "from": {"type":"individual","accountId":"<uuid>"},
       "payment": {"method":"sepa","recipient": {"iban":"GB33...","bicSwift":"BUKBGB22","name":"John","surname":"Doe","country":"GB"}}
     }'
   ```
7. **List transactions (cursor)** — `GET /v1/transactions`
   ```bash theme={null}
   curl -X GET "$CLIENT_API_BASE/v1/transactions?accountId=<uuid>&limit=50&sortOrder=descending&lastKey=<cursor>" \
     -H "Authorization: Bearer $TOKEN"
   ```

### B) Company onboarding (KYB)

1. **List companies** — `GET /v2/companies`
2. **Get KYB access token** — `GET /v2/companies/{companyId}/kyb-access-token`
3. **Accept contract (company)** — `POST /v2/companies/contract-accept`

***

## Crypto features (under Client API)

The crypto‑exchange feature set lives under the same base URL, namespaced at `/crypto-exchange`.

* **List orders (paginated)** — `GET /crypto-exchange/orders`
  ```bash theme={null}
  curl -X GET "$CLIENT_API_BASE/crypto-exchange/orders?pageLimit=10&pageSort=desc&pageKey=<cursor>" \
    -H "Authorization: Bearer $TOKEN"
  ```
* **Get order** — `GET /crypto-exchange/orders/{orderId}` (eventual consistency)
* **Create order** — `POST /crypto-exchange/orders`
* **Create wallet (external account)** — `POST /crypto-exchange/wallets`
* **Create payout (transaction)** — `POST /crypto-exchange/payouts`

<Info>
  Pagination differs by area: core banking uses `limit/lastKey`; crypto uses `pageLimit/pageKey/pageSort`.
</Info>

***

## Status codes & patterns

* **200 OK** — successful GET/POST (lists, tokens, reads)
* **201 Created** — resource/operation created (transfers, accounts, orders)
* **400 / 403 / 404** — validation/auth/lookup errors
* **500** — server error

**Best practices**

* Include `Authorization: Bearer <access_token>` on **every** request.
* Set `Content-Type: application/json` for bodies.
* Prefer **cursor pagination** (`lastKey` or `pageKey`) over offset.
* Prefer new endpoints under `/v2` when available.
* Avoid deprecated paths such as `/account/details/{account}`.

***

## Quick reference

| Feature                  | Endpoint                                                         |
| ------------------------ | ---------------------------------------------------------------- |
| Get client profile       | `GET $CLIENT_API_BASE/client`                                    |
| Initiate client          | `POST $CLIENT_API_BASE/client`                                   |
| Accept contract (client) | `POST $CLIENT_API_BASE/v2/clients/contract-accept`               |
| Get KYC token            | `GET $CLIENT_API_BASE/v1/kyc/access-token`                       |
| List companies           | `GET $CLIENT_API_BASE/v2/companies`                              |
| Get KYB token            | `GET $CLIENT_API_BASE/v2/companies/{companyId}/kyb-access-token` |
| Create account           | `POST $CLIENT_API_BASE/v1/accounts`                              |
| Get bank details         | `GET $CLIENT_API_BASE/v1/ext-accounts/{extAccountId}`            |
| External transfer        | `POST $CLIENT_API_BASE/v2/transfer`                              |
| Internal transfer        | `POST $CLIENT_API_BASE/v2/transfer/internal`                     |
| List transactions        | `GET $CLIENT_API_BASE/v1/transactions`                           |
| List orders              | `GET $CLIENT_API_BASE/crypto-exchange/orders`                    |
| Get order                | `GET $CLIENT_API_BASE/crypto-exchange/orders/{orderId}`          |

***

## Next steps

* Configure Cognito (User Pool, Web Client ID, Hosted UI/PKCE) and CORS allow‑lists.
* Use **Dev** for integration; switch env vars to **Prod** at go‑live.
* Enable crypto features if required; endpoints will be available under `/crypto-exchange`.