Authentication – Client secret with subject assertion

In field tables, the presence column shows M for mandatory, O for optional, and C for conditional — mandatory only in the situation the description gives. Paths are relative to the base URL for your environment. Examples use $BASE_URL for that value and shorten long tokens with an ellipsis. The API refers to an existing subscriber as the subject, which is why paths and fields carry names such as subjectRef and subject_ref.

Apart from the token endpoint, every error is an RFC 9457 problem document with content type application/problem+json.

{
  "type": "https://api.npscentral.in/problems/validation-rejected",
  "title": "The request was understood and refused.",
  "status": 422,
  "category": "VALIDATION_REJECTED",
  "code": "MODIFICATION_REQUEST_INVALID",
  "detail": "The request body does not match the modification type.",
  "retryable": false,
  "requestId": "3f6c1a9e-…",
  "errors": [
    { "field": "pop[0].popRegNo", "code": "MODIFICATION_REQUEST_INVALID", "message": "…" }
  ]
}

A 429 response carries a Retry-After header; wait at least that long before retrying. The token endpoint follows OAuth 2.0 instead and returns { "error": "<code>" } (section 5.4).

Present the secret in one place only. A request with both a Basic header and a client_secret field is refused, as is any request that puts the secret in the query string.

curl -X POST "$BASE_URL/v1/auth/partner-token" \
  -u "pop-acme:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="subject:read contribution modification"

The response is sent with Cache-Control: no-store.

invalid_client deliberately does not say which check failed, so that the response gives nothing away to someone guessing credentials.

NPS Central relies on your assertion and does not verify the subscriber itself. Before you present one, you must have:

The assertion records how you authenticated them (amr) and when (auth_time). Both must be accurate.

A compact JWS, signed HS256 with your encryption key: the 32 bytes you obtain by decoding the key's base64url value. Never sign with your client secret.

{
  "iss": "pop-acme",
  "sub": "cust-88213",
  "aud": "https://uat.example.in/api/v1/auth/partner-token",
  "jti": "a7d9e1c4-2b6f-4a83-8e15-0c3f9b7d2e61",
  "iat": 1791547200,
  "exp": 1791547320,
  "subject": { "pran": "110012345678" },
  "amr": ["otp"],
  "auth_time": 1791547180
}

Under your agreement with NPS Central, you are responsible for having verified and authenticated the subscriber, and obtained their consent, before presenting an assertion. Keep the jti, sub, amr and auth_time of every assertion you send; NPS Central records the same values, and they are what either side will refer to if a session is ever questioned. Because the same encryption key signs your assertions and encrypts your payloads, revoking it stops both.

Ordinary API calls do not extend the idle timeout. Call refresh when the subscriber is active in your application, rather than on a timer. Refreshing never moves the session past its 60 minutes. A session also ends early if the subject:assert grant is withdrawn from your account.

CONTACT_UPDATE, BANK_UPDATE and TIER2_ACTIVATION move either the subscriber's money or the channel every later code is sent to, so each needs your own fresh OTP. Immediately before filing, authenticate the subscriber with an OTP that your application sends, and state the result in the request's verification, with a verifiedAt no more than 5 minutes old. This is separate from the authentication your assertion records. A missing or stale verification is refused with 422 PARTNER_VERIFICATION_REQUIRED.

A call outside your scopes returns 401 AUTH_FAILED, the same response as an invalid token. If a freshly issued token receives it, check the scope field returned with that token.

Records belong to the partner that created them. Another partner's record, a record the subscriber created elsewhere, and an identifier that does not exist all return the same 404 NOT_FOUND.