API reference / Depository / Broker

Broker login: callback

Step 2 of a hosted broker login: exchange what the broker sent back for a live connection.

POST/v1/broker/login/callback
Authentication
Bearer token
Scope
broker:read

Before you integrate

  • Step 2 of 2, after login start. The state must come from your own account, be under 10 minutes old and not have been used before.
  • The result is a live connection; use its connection_id on the other broker calls.

Request body

FieldTypeRequiredDescription
statestringYesThe state value from login start, unchanged; 1 to 4000 characters.
paramsobjectNoEvery query parameter the broker put on your redirect URL, as received (for example request_token or code); each value up to 2000 characters. Defaults to empty.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/broker/login/callback' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "state_from_login_start",
  "params": {
    "request_token": "token_from_broker_redirect"
  }
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "connection_id": "bconn_a1b2c3d4e5f60718",
    "broker": "zerodha",
    "mode": "live",
    "label": "zerodha (live)",
    "status": "connected"
  }
}

Response fields

FieldTypeDescription
connection_idstringId to pass as connection_id on every other broker call.
brokerstringThe broker this connection is for.
modestringsandbox or live.
labelstringThe connection's label.
statusstringAlways connected on success.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.