| name | abdm-auth |
| description | Set up Eka ABDM Connect authentication - developer console signup, client_id/client_secret provisioning, access/refresh token lifecycle, long-lived tokens, sharing keys, and BYOA. Use when the user needs credentials, gets 401/403 errors, asks about tokens, or at the start of any milestone integration (auth is always step one). |
ABDM Connect Authentication
Credential acquisition (one-time, human-in-the-loop)
The only steps that require the human integrator:
- Sign up at https://login.eka.care (Google/Apple/email) and create a workspace → lands on Eka Developer Console (https://console.eka.care).
- Quick Actions → Manage API Credentials → create an API client → copy
client_id and client_secret (secret shown once only).
- Optional: create a Long-Lived Token (three-dot menu) for pure server-to-server integrations with no refresh logic.
- Optional: Sharing Key from https://hub.eka.care/account/ to access another workspace (pass
sharing_key in the login body).
Agent behaviour: when starting an integration, ask the user for client_id + client_secret (or long-lived token) and target environment (sandbox https://api.dev.eka.care vs prod https://api.eka.care). Store them ONLY in the client project's environment mechanism (.env + secret manager). Never hardcode, never commit, never print the secret back.
Token flow
POST {BASE}/connect-auth/v1/account/login
{ "client_id": "...", "client_secret": "...", "sharing_key": "optional" }
→ { access_token, expires_in, refresh_token, refresh_expires_in }
- Send access token in the
auth header (some APIs accept Authorization: Bearer). Fetch the specific endpoint's doc page to confirm which header it uses.
- On
401 → call refresh: /api-reference/authorization/refresh-token-v2.md has the schema.
- Cache the token in memory/Redis with TTL slightly under
expires_in; never persist to DB.
Implementation checklist (generate this in the client codebase)
BYOA (Bring Your Own ABDM credentials)
Clients with their own NHA bridge credentials can plug them in: fetch /api-reference/authorization/byoa.md. Default (recommended) is Eka-managed credentials via the Eka Bridge.
Common failures
| Symptom | Cause | Fix |
|---|
| 401 on login | wrong client_id/secret or wrong env (sandbox creds on prod URL) | verify env pairing |
| 401 mid-session | expired access token | refresh flow |
| 403 | credential lacks scope for that product/API | check console client config, contact Eka |
| Token works on one API, not another | wrong header name (auth vs Authorization) | fetch that endpoint's doc page |
Full docs map: ../abdm-overview/references/docs-map.md.
