abdm-auth

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:

1. Sign up at https://login.eka.care (Google/Apple/email) and create a workspace → lands on Eka Developer Console (https://console.eka.care).
2. Quick Actions → Manage API Credentials → create an API client → copy client_id and client_secret (secret shown once only).
3. Optional: create a Long-Lived Token (three-dot menu) for pure server-to-server integrations with no refresh logic.
4. 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)

• Config: EKA_CLIENT_ID, EKA_CLIENT_SECRET, EKA_BASE_URL from env
• Token manager: fetch-on-start, cached, auto-refresh on 401, single-flight (no thundering herd)
• HTTP client wrapper that injects the auth header and retries once after refresh
• Unit test: 401 → refresh → retry succeeds
• Official auth SDKs exist for Go/Java/Python — fetch /api-reference/authorization/sdks/{go,java,python}-sdk.md and prefer them if the client stack matches.

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.