Connect GST Taxpayer
The Connect GST Taxpayer block establishes a GST taxpayer session for a GSTIN in one step: the workflow pauses here, and a link lets a human request and enter the OTP GST sends to the taxpayer's own registered contact. Every GST Filing and GST Ledgers tool for that GSTIN resolves the resulting session automatically -- once connected, those tools need no further credential.
A GSTIN only needs to be connected once per workspace, not once per workflow. If it's already connected, drop the tools you need directly -- this block is only for establishing the connection the first time, or after the session lapses.
How It Works
Execution reaches the block. Nothing is requested from GST yet -- the workflow pauses and persists its state, the same underlying mechanism Human in the Loop uses.
A connect link opens at the block's url output. If a delegate email was configured, that link is also emailed to them directly.
Whoever opens the link clicks "Get verification code." This is the moment GST actually sends the OTP -- nothing is requested until this click, since neither this integration nor Sandbox's own docs state how long a GST OTP stays valid.
The code is entered and verified. On success, the session is saved and the workflow resumes -- the block's output now shows connected: true and the session's expiry.
The connect link needs no Mandala account to open -- knowing it is what grants access, the same bearer-capability model Human in the Loop's resume link and the Batch confirmation gate's confirm link both use. This is what lets a delegate who's never used Mandala complete the OTP step themselves.
Configuration Options
GSTIN - The GSTIN to connect, e.g. 24ABKCS2033B1ZV.
GST portal username - The taxpayer's own gst.gov.in login username.
Delegate email (optional) - If someone other than the workflow author receives the OTP, enter their email here. They get the connect link by email and never need a Mandala account. Leave blank if you hold OTP access yourself.
Session Lifetime
The resulting session lasts about 6 hours, per GST's own documented window. Once it lapses, GST Filing/Ledgers reads for that GSTIN fail with a clear "reconnect" error until either:
- A fresh Connect GST Taxpayer run (a new OTP handshake), or
- A Refresh GST Taxpayer Session tool call, which extends the session by another 6 hours without a new OTP -- as long as it's called before the session actually lapses.
Reconnecting or revoking an existing connection is also available from Settings -> Government Portal without touching a workflow -- see Connecting a GSTIN.
Inputs and Outputs
connected: Whether the session was successfully established
gstin: The GSTIN that was connected
expiresAt: ISO timestamp the session expires at (~6 hours out)
url: The connect/verify page URL for this pause
Best Practices
- Use a delegate email whenever the workflow author isn't the one holding OTP access. The alternative -- watching the paused-executions list and relaying a code manually -- doesn't scale and is easy to miss.
- Reconnect proactively for workflows that run more than a few hours apart. A ~6-hour session means anything on a daily or slower schedule needs either a Refresh step first or a fresh connect, not an assumption the session is still good.
- Connect once per GSTIN, not once per workflow. Every other GST Filing/Ledgers tool and every binding action for that GSTIN reuses the same connection automatically.