---
name: cas-core
description: "Cas integration foundation: environments, authentication, grant lifecycle (token → Cas Link → exchange → API calls), webhooks and error handling. Applies to every Cas product."
---

# Cas — core

> Source: https://cas.so/en/quickstart · Markdown: https://cas.so/en/quickstart.md

_This skill is generated from the Cas documentation. When you need details (schemas, error codes, examples), fetch the latest Markdown from the links below instead of guessing._

## Environments & authentication

| Environment | Base URL |
| --- | --- |
| Sandbox | `https://sandbox.bankhub.dev` |
| Production | `https://production.bankhub.dev` |

Every server-side call carries: `x-client-id`, `x-secret-key`, `X-BankHub-Api-Version: 2023-01-01`.
Grant-scoped endpoints add `Authorization: <accessToken>` — the bare token, with NO `Bearer` prefix.
Always check each endpoint's own `.md` before coding; a few APIs take different headers.

## The flow shared by every Cas product

1. **Create a grant token** — your server calls `POST /grant/token` with the product `scopes` and receives a `grantToken` and its `expiration`.
2. **Open Cas Link** — the client opens Cas Link with the `grantToken`; the end user picks their institution and authenticates.
3. **Receive a `publicToken`** — Cas Link returns it to the client once the user is done.
4. **Exchange for an `accessToken`** — your server calls `POST /grant/exchange`; store `accessToken` + `grantId`.
5. **Call the product APIs** — using the `accessToken`.
6. **Handle webhooks** — Cas posts transaction and grant events to your endpoint; process them idempotently.

## Read before writing code

- [Get started](https://cas.so/en/quickstart.md)
- [Cas Link](https://cas.so/en/general/link.md)
- [Create grant token](https://cas.so/en/general/api/grant/create.md)
- [Exchange public token for an access token](https://cas.so/en/general/api/grant/exchange.md)
- [Remove Grant](https://cas.so/en/general/api/grant/remove.md)
- [Pause Grant](https://cas.so/en/general/api/grant/pause.md)
- [Update mode](https://cas.so/en/general/link/update-mode.md)
- [Webhook](https://cas.so/en/general/api/webhook.md)
- [Errors](https://cas.so/en/errors.md)
- [Production checklist](https://cas.so/en/launch-checklist.md)

## Rules you must follow when writing code

- `clientId` / `secretKey` live on the server in environment variables only — never ship them to a client, never commit them.
- Request only the `scopes` the product needs; extra scopes mean extra cost and risk.
- Avoid duplicate grants: check your database for a live grant before opening Cas Link again.
- Store `accessToken` and `grantId` encrypted and linked to your user; one user may hold several grants. Never surface these values in the UI.
- Log `requestId` (on every response) and `grantId` (on grant-related responses) for every call — this is what Cas support needs to trace an issue.
- Every API call needs a timeout and backoff retry for transient failures; never blindly retry money-moving calls (use your own idempotency key).
- Webhooks: accept them only from Cas IPs, return 2xx fast and process asynchronously, and make handling idempotent — deliveries can repeat or arrive out of order.
- Handle `GRANT_LOGIN_REQUIRED` by reopening Cas Link in Update mode instead of making the user relink from scratch.
- Handle `GRANT` webhooks: `USER_PERMISSION_REVOKED`, `GRANT_DELETED`, `GRANT_PAUSED`, `DEFAULT_UPDATE` — reflect the link state in your system.
- Call `/grant/remove` when a user unlinks in your app, and handle the OTP-verification branch.
- Run the whole flow on `https://sandbox.bankhub.dev` first; switch to `https://production.bankhub.dev` together with the production secrets.

## Before going to production

Verify against the **entire** production checklist: https://cas.so/en/launch-checklist.md

For every checklist item, point at the code (file path + line) that proves it is handled, or state why it does not apply. Never tick an item without evidence.

## Available products

Each product ships its own skill; install one more whenever you add a product:

- **Auto Debit** — `cas-auto-debit` — https://cas.so/en/skills/cas-auto-debit/SKILL.md
- **Balance Hook** — `cas-balance-hook` — https://cas.so/en/skills/cas-balance-hook/SKILL.md
- **Deeplink** — `cas-deeplink` — https://cas.so/en/skills/cas-deeplink/SKILL.md
- **EKYC** — `cas-ekyc` — https://cas.so/en/skills/cas-ekyc/SKILL.md
- **IDKit** — `cas-idkit` — https://cas.so/en/skills/cas-idkit/SKILL.md
- **Invoice Hub** — `cas-invoice-hub` — https://cas.so/en/skills/cas-invoice-hub/SKILL.md
- **Pay Out** — `cas-pay-out` — https://cas.so/en/skills/cas-pay-out/SKILL.md
- **Payment Initiation** — `cas-payment-initiation` — https://cas.so/en/skills/cas-payment-initiation/SKILL.md
- **QR Pay** — `cas-qr-pay` — https://cas.so/en/skills/cas-qr-pay/SKILL.md
- **Transactions** — `cas-transactions` — https://cas.so/en/skills/cas-transactions/SKILL.md
- **TVAN** — `cas-tvan` — https://cas.so/en/skills/cas-tvan/SKILL.md
- **Virtual Account** — `cas-virtual-account` — https://cas.so/en/skills/cas-virtual-account/SKILL.md