ABDM v3 · M1–M4 implemented
Sandbox keys, issued on signup

Developers ABDM sandbox

An ABDM sandbox you can call today

NHA’s sandbox is where every ABDM integration is built and tested, and getting into it normally starts with a registration and a wait. Here, sandbox API keys are issued the moment you verify your email, and your first call reaches the NHA sandbox the same afternoon.

Get sandbox keys Sandbox exit checklist

01 Two sandboxes

Which sandbox you actually need

There is one ABDM sandbox, run by NHA. There are two ways to reach it: with your own NHA client id, or through a connector that already holds one.

NHA’s sandbox, directly Your own client id

  • Register at sandbox.abdm.gov.in. NHA issues a sandbox client id and secret for your software, which takes days rather than minutes.
  • Build the gateway side yourself. Session tokens, request ids, the public bridge URL ABDM calls back on, and verification of the gateway’s signed callbacks.
  • Build the crypto yourself. RSA sealing for Aadhaar and OTPs; Fidelius — Curve25519 ECDH, HKDF-SHA256, AES-256-GCM — for every record transfer.
  • Find the host quirks yourself. Several widely repeated registry hostnames do not route from many networks.

Sandbox keys here Issued on signup

  • Keys on email verification. A sandbox client id (swk_sand_…) and secret (sk_sand_…), no form to wait on.
  • The ABDM client identity is carried for you. The connector calls the NHA sandbox under its own registration, with your facility on each request.
  • Callbacks arrive as webhooks. ABDM’s asynchronous answers are verified, correlated and posted to your HTTPS endpoint, signed.
  • The same code goes to production. Environment is a property of the credential, not the URL.

02 Getting access

From signup to a sandbox call

Everything up to production is self-service. Nobody has to approve a sandbox account, because sandbox data is synthetic.

  1. Sign up and verify your email

    Your organization is created on the Free plan and the sandbox works immediately. Production stays closed until it is approved.

  2. Register an application, issue a key

    An application is one integration; a credential belongs to it. The secret is shown once and stored hashed. Narrow a key’s scopes at issue time, and add an IP allowlist if your egress is fixed.

  3. Seed the starter data

    One action fills your sandbox with a facility, four patients and four care contexts, so there is something to link and share on day one. The facility is deliberately not marked bridge-linked: no real HFR registration happened, and pretending otherwise would hide a step you will need later.

  4. Exchange the key for a token

    POST /v1/auth/token with the client-credentials grant. The token lasts an hour and says which environment it belongs to — check it with GET /v1/auth/whoami before anything else.

first token Sandbox 
# exchange the key
POST /v1/auth/token

{
  "client_id": "swk_sand_…",
  "client_secret": "sk_sand_…",
  "grant_type": "client_credentials"
}

← 200 OK
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "patient:read patient:write …",
  "environment": "sandbox"
}

# confirm what the token carries
GET /v1/auth/whoami

← 200 OK
{
  "name": "HMIS integration",
  "capabilities": ["m1_abha", "m2_hip"],
  "scopes": ["patient:read", "patient:write"]
}

03 Coverage

What you can test in the sandbox

Every milestone is open on the Free plan. The API reference in the portal has curl, Python and JavaScript for each endpoint, and exports the whole API as a Postman collection that makes real sandbox calls with your key.

M1

ABHA creation and login

Enrolment by Aadhaar OTP and by mobile, address suggestion and choice, login to an existing ABHA, profile, card and QR. Linking the new ABHA to your patient raises abha.created or abha.verified.

Not in NHA’s sandbox · driving-licence enrolment

M2

Records as a HIP

Register patients by MRN, create care contexts with a FHIR bundle, link them with POST /v1/care-contexts/link, and answer discovery from the citizen’s PHR app. The outcome arrives as care_context.linked or care_context.link_failed.

Asynchronous · 202 means accepted, not linked

M3

Consent and data as an HIU

Raise a consent request, watch it resolve to consent.granted or consent.denied, request the health information against the artefact and read the decrypted bundles from GET /v1/records.

Fidelius · the full encrypted round trip, not a stub

M4

HFR and HPR registries

Facility search and master data, the four-step HFR registration, bridge linkage, HPR professional lookup, and HPR ID creation and registration.

One host · both sandbox registries live on apihspsbx.abdm.gov.in

Want the milestone detail first? The M1, M2, M3 and M4 guide explains what each covers, and how ABDM integration works walks a record from HIP to HIU.

04 Known behaviour

What the NHA sandbox does that looks like your bug

Seen against the live sandbox, and worth recognising rather than debugging.

401

A silent 401 is a throttle, not a bad secret

Minting ABDM session tokens in a tight loop gets a 401 with an empty body for several minutes. A real credential rejection carries a JSON body. Re-authenticating in response makes the throttle worse, which is why the connector caches session tokens and refreshes at most once per 401.

Your side · use webhooks rather than polling; the connector’s ABDM rate limit is shared

403

Forbidden on linking usually means a role, not code

A 403 on ABDM’s link-token or care-context endpoints usually means the client id lacks the HIP role or an API subscription. On data-flow endpoints it has been traced to subscription gaps on ABDM’s side.

Passed through · ABDM’s own error code reaches you in the error details

Linkage

A facility that authenticates can still be refused

A facility in HFR whose services are not linked to the bridge authenticates perfectly and has every linking call rejected, and no ABDM error says why. Bridge linkage in the portal is the step, and activation refuses to pretend it happened.

Refused · software_linkage_unconfirmed

Docs

The documentation host goes down; the APIs do not

sandbox.abdm.gov.in’s documentation pages return 503 intermittently. The API hosts are unaffected, so an unreachable doc page is not a sign your integration is broken.

05The sandbox exit process

Sandbox exit is how an integration earns production access, and it is NHA’s process, not ours. It starts from a form in the sandbox account and runs through four stages:

  1. Functional testing by an NHA-empanelled agency, which runs ABDM’s test-case sheets against your deployment and issues a report.
  2. A security audit by a CERT-In empanelled auditor, ending in a Safe-to-Host certificate once findings are closed.
  3. NHA committee review of the testing report, the certificate and the production keys template.
  4. Per-facility linkage in production: each HIP site registered in HFR with its services linked to the bridge.

The testing agency and the auditor bill for their time and book it in advance. The cheapest thing you can do is arrive with every scenario already run against the real sandbox.

06Before you book the testing agency

  • Every scenario you will claim has been walked through once against the real sandbox, not a mock — a mock speaks ABDM’s shapes, not its rules.
  • Each run’s abdm_request_id is noted from GET /v1/audit/abdm-transactions. When the agency asks what you sent, that id is what their systems index on.
  • Each flow’s correlation id is kept too: GET /v1/audit/trace/{correlation_id} shows your call, the ABDM calls it caused and the audit events, in order.
  • At least one facility has an HFR entry, a hip_id and a hiu_id, and a successful bridge linkage.
  • Your webhook endpoint verifies signatures and handles care_context.link_failed, consent.denied and health_information.failed, not only the happy events.

07What has to be shown by hand

Most ABDM test cases have a user-interface half: consent text in the citizen’s language, a resend-OTP timer, how the ABHA card is displayed, the OTP arriving on a phone, a care context appearing in the PHR app. The connector is an API, so that half is demonstrated in your HMIS.

Record one walkthrough of each claimed milestone against the real sandbox, on the software a hospital will actually use, showing the citizen’s side as well as the hospital’s. It becomes the evidence pack for the agency, and it costs an afternoon.

08Declare these up front

Stating a limit on the exit form is quicker than having the agency discover it. On this connector, three are worth writing down:

  • ABHA creation by driving licence exists but is not enabled in NHA’s sandbox, so it cannot be demonstrated there.
  • Biometric ABHA creation is off by default and needs NHA to enable the methods for the client id; demographic and offline creation are not implemented.
  • The connector is API-first: user-interface test cases are shown in the integrating HMIS.

09Two approvals, not one

NHA’s approval is the first. The second is this platform’s: you request production access from the portal and a person reviews it, because crossing that line means your traffic reaches real citizens’ records. Until it is approved, production cannot be selected, a production key cannot be issued, and a request that tries gets 403 production_access_not_granted.

Once approved, going live is a new credential. Endpoints, payloads and webhooks do not change. Sandbox facilities and patients stay in the sandbox, so each production site is registered and linked for real.

10 Timeline

How long sandbox to production takes

The sandbox build is the part you control. The audit is usually the longest stage.

Typical elapsed time per stage. Bars are drawn to one 16-week axis.
StageWhat happensTypical duration
Sandbox build Integrate every claimed flow and run it against the NHA sandbox 2–6 weeks
Functional testing An NHA-empanelled agency runs the test-case sheets 1–2 weeks
WASA security audit A CERT-In empanelled auditor, ending in a Safe-to-Host certificate 5–8 weeks
NHA review Committee review of the report, certificate and production keys template 2–4 weeks

A connector shortens the build, not the certification. See the ABDM integration guide for what each milestone involves, and the ABDM API overview for the surface you build against.

Make your first sandbox call today

Verify your email, take the key, seed the starter facility and link a care context. Nothing to pay until production.

Get sandbox keys API reference

FAQ Common questions

Frequently asked questions

How do I get ABDM sandbox credentials?
Either register your software at NHA's sandbox and wait for a client id, or sign up here: sandbox API keys are issued as soon as you verify your email, and the connector carries the ABDM client identity for you.
Is the ABDM sandbox free?
Yes. NHA does not charge for its sandbox, and sandbox access on this platform is free within the call limits of the free plan. You pay nothing until you move to production.
What is sandbox exit in ABDM?
The process that turns a sandbox integration into production access: an exit form in the sandbox account, functional testing by an NHA-empanelled agency, a security audit ending in a Safe-to-Host certificate, and review by NHA before production keys are issued.
Does code written against the sandbox work in production?
Yes. The environment is a property of the API credential, not of the URL, so going live means swapping the key. The endpoints, payloads and webhooks are the same; what production adds is an HFR entry and bridge linkage for each real site.