API reference / Depository / Broker

Broker login: start

Step 1 of a hosted broker login: returns the broker's own login page to send your user to.

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

Before you integrate

  • Step 1 of 2. Send the user to redirect_url. After they log in, the broker sends them to your redirect_uri with query parameters.
  • Then call login callback with state and those parameters within 10 minutes. A state can be used only once.
  • A broker without a login page (for example angel, dhan, groww, shoonya, xts) is refused here; get its token from the broker and use connect with credentials.

Request body

FieldTypeRequiredDescription
brokerstringYesBroker name, 2 to 30 characters. Hosted login works for zerodha, upstox, fyers, motilal, flattrade, zebu, tradesmart and arrow.
api_keystringYesYour API key with that broker, 1 to 200 characters.
api_secretstringNoYour API secret, 1 to 200 characters. Every broker that supports hosted login needs it; it is sealed inside state and never reaches the browser.
redirect_uristringYesThe URL on your side the broker returns the user to; a full URL up to 500 characters, registered with the broker.
labelstringNoYour name for the connection that will be created, up to 80 characters.
client_idstringNoBroker client code, 1 to 100 characters; needed by motilal.

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/start' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "broker": "zerodha",
  "api_key": "your_broker_api_key",
  "api_secret": "your_broker_api_secret",
  "redirect_uri": "https://app.example.com/broker/callback"
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "broker": "zerodha",
    "redirect_url": "https://broker.example.com/connect/login?v=3&api_key=your_broker_api_key&state=c3RhdGU",
    "state": "c3RhdGVfZnJvbV9sb2dpbl9zdGFydA",
    "expires_in_sec": 600
  }
}

Response fields

FieldTypeDescription
brokerstringThe broker.
redirect_urlstringThe broker's own login page; send the user here.
statestringOpaque value to send back unchanged in login callback.
expires_in_secintegerSeconds before state stops working (600).

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.