AlkiraiLinkDocs
Quickstart

Get started

Quickstart

Connect the sandbox bank and read 6 months of its transactions, in five calls from a terminal. Nothing here reaches a real institution.

You need your client ID, a sandbox secret and one redirect URI registered for the sandbox. During early access our team issues them: write to hello@alkirai.com. Any https address you control will do as the redirect URI; for this walk-through nothing needs to be running there.

  1. Keep your client ID and secret in the shell

    Every call carries both: the client ID in the X-Client-Id header and the secret in X-API-Key. Keep the secret on your server, and never in an app.

    Terminal

    export ALKIRAILINK_CLIENT_ID="your client ID"
export ALKIRAILINK_SECRET="your sandbox secret"

  2. See what you can connect

    A sandbox secret is offered the sandbox institutions only. sandbox_bank is the one this guide connects.

    curl "https://api.alkirai.com/v1/institutions" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

  3. Start a Connect session

    Put your registered redirect URI in place of https://example.com/connected. state is yours: Connect sends it back on the redirect, so you can tie the result to the person who started it.

    curl -X POST "https://api.alkirai.com/v1/connect/sessions" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "institution_id": "sandbox_bank",
    "redirect_uri": "https://example.com/connected",
    "state": "person-42"
  }'

    The answer holds a link_url, good for 10 minutes.

  4. Sign in through Connect

    Open the link_url in a browser, as the person would. Sign in to the sandbox bank as jam_dung with the password fi_wi.

    When Connect finishes, it sends the browser to your redirect URI with a public_token (and your state) in the address. Copy the token from the address bar. It lasts 60 seconds and works once, so go straight on.

  5. Exchange the token for a connection

    export PUBLIC_TOKEN="the token from the address bar"
    curl -X POST "https://api.alkirai.com/v1/connect/exchange" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d "{\"public_token\": \"$PUBLIC_TOKEN\"}"

    Keep the connection_id it returns: every later call takes it. In your own server, exchange the token as soon as your redirect is called. A connection nobody exchanges is deleted after 5 minutes.

  6. Read accounts and transactions

    POST /v1/connections/{connection_id}/refresh reads both from one sign-in. Send no cursor the first time.

    export CONNECTION_ID="the connection_id"
curl -X POST "https://api.alkirai.com/v1/connections/$CONNECTION_ID/refresh" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

    Trimmed to one account and two transactions, the sandbox bank answers like this:

    Response

    {
  "accounts": [
    {
      "account_id": "sbx_99162537b830abb0c7e6",
      "name": "Sandbox Chequing",
      "type": "depository",
      "subtype": "checking",
      "mask": "0001",
      "currency": "JMD",
      "balance_current": 245318.5,
      "balance_available": 241818.5,
      "balance_limit": null
    }
  ],
  "transactions": {
    "added": [
      {
        "transaction_id": "sbx_e3bbc22e9a8bc1db0f5642de",
        "account_id": "sbx_99162537b830abb0c7e6",
        "amount": 15777.84,
        "currency": "JMD",
        "date": "2026-10-17",
        "description": "POS BLUE MOUNTAIN GROCERS",
        "merchant_name": "Blue Mountain Grocers",
        "pending": false,
        "raw_category": "POS PURCHASE"
      },
      {
        "transaction_id": "sbx_03dcdc169849d4a98a2e01d6",
        "account_id": "sbx_99162537b830abb0c7e6",
        "amount": 40000.0,
        "currency": "JMD",
        "date": "2026-10-20",
        "description": "PAYMENT TO VISA 0003",
        "merchant_name": "",
        "pending": false,
        "raw_category": "TRANSFER"
      }
    ],
    "modified": [],
    "removed_ids": [],
    "cursor": "…",
    "partial_failure": null
  }
}

    Both amounts are positive because both are money leaving the account. Store the cursor with the connection and send it next time, as ?cursor=, to get only what changed since.

  7. Remove the connection

    The sandbox allows 25 live connections per key, so clean up as you go.

    curl -X DELETE "https://api.alkirai.com/v1/connections/$CONNECTION_ID" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Next