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
| Field | Type | Required | Description |
|---|---|---|---|
broker | string | Yes | Broker name, 2 to 30 characters. Hosted login works for zerodha, upstox, fyers, motilal, flattrade, zebu, tradesmart and arrow. |
api_key | string | Yes | Your API key with that broker, 1 to 200 characters. |
api_secret | string | No | Your 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_uri | string | Yes | The URL on your side the broker returns the user to; a full URL up to 500 characters, registered with the broker. |
label | string | No | Your name for the connection that will be created, up to 80 characters. |
client_id | string | No | Broker 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
| Field | Type | Description |
|---|---|---|
broker | string | The broker. |
redirect_url | string | The broker's own login page; send the user here. |
state | string | Opaque value to send back unchanged in login callback. |
expires_in_sec | integer | Seconds 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.