Guides

Connecting

AlkiraiLink Connect is the hosted sign-in. The person types their details and any one-time code into Connect, so your app never handles them, and your server gets a connection back.

Before anyone connects

GET /v1/institutions says what each institution can do, and two of its fields decide how your app keeps a connection current. Read them before you offer an institution.

`sync_mode`	`runs_on`	What your app does
`unattended`	`server`	Connect once through Connect, then refresh on your own schedule with nobody present.
`attended`	`server`	Every refresh needs the person. A read without them is refused with `mfa_required`, and nothing is broken.
`attended`	`client`	The person signs in on their own device, through the mobile SDK. Connect isn't used: see Sign-in sync.

Also read beta. A beta institution works, and is still being proven; tell people before they rely on it. supports_transactions and supports_balances say what a connection there returns, so you can say what you'll show before anybody signs in.

Start a session

Call POST /v1/connect/sessions from your server with the institution, a redirect URI and, if you like, a state.

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"
  }'

redirect_uri must be registered for the environment your secret belongs to, and is matched exactly, character for character. For a web view in your app, register a custom scheme with a dot in it, such as com.example.app://connected.
state comes back on the redirect unchanged. Use it to tie the result to the person who started it, and check it before you exchange the token.
The session lasts 10 minutes. Open its link_url in the person's browser or in a web view.

What comes back

When the person finishes, Connect's last page sends the browser to your redirect URI with public_token and state added to its query. It is a navigation the page makes, not a server redirect, so a web view's navigation handler sees it, custom schemes included.

Pressing Sign in twice is harmless: Connect makes one sign-in per session, and a second press gets the first one's answer. That also means a failed sign-in stays failed for that session. To let the person try again, start a new session.

Exchange the token

Pass the public_token to your server and call POST /v1/connect/exchange straight away.

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\"}"

A public token lasts 60 seconds and works once.
A connection nobody exchanges is deleted after 5 minutes, with the details the person typed.
Store the connection_id against the person. institution_name is there to label it, and can be empty, so keep a fallback.
When unattended_blocked is set, the connection works now but can't refresh without the person. Show them its sentence: it says what to fix at the institution.

For 15 minutes after the connect, reads are answered from the connect's own sign-in, so reading straight away costs no sign-in. See Syncing and budgets.

Reconnecting

Connecting the same institution again makes a new connection with a new connection_id; it never revives the old one. When a person reconnects, remove their old connection: it still holds their stored details.

Removing a connection

DELETE /v1/connections/{connection_id} deletes the connection and the sign-in details stored for it. It is safe to repeat.

Show the person action_required when it isn't empty. Some institutions keep a record of each device that signs in, such as a trusted-device entry, and limit how many there can be. When AlkiraiLink can't clear its own, the sentence tells the person where to clear it, so they can still connect next time.