1 of 1

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

In common for all services of the Identity Building Block, the API expects the calling Partner has been already authenticated and authorized to access the service. For detailed specifications of APIs with input/output formats please refer to API specifications defined in YAML in the corresponding GitHub repository.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Identity Building Block can be found in this GitHub repository.

API standards

The microservice interfaces are defined as per OPENAPI Ver3.0 standards.
For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.

8.1 Identity Usage

The Identity usage APIs are a set of OpenAPI specifications exposed by the Identity Building Block to other building blocks and applications for user verification.

The Identity usage APIs are based on the following principles:

Verification APIs are inspired by OpenID Connect protocol which simplifies integrations using pre-existing libraries
Only secure options in OpenID connect should be supported to ensure the user data is handled securely
All biometric capture for user verification should be done using Secure Biometrics Interface standards

Service Group: Client Management

For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.

Detailed API schemas written in YAML that define REST API endpoints for each of the services mentioned above are available on GitHub located at the Identity-Provider YAML.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.

8.2 Identity Management

The Enrollment APIs are a set of OpenAPI specifications exposed by the Identity Building Block ‘Enrollment Server’ service to any enrollment client.

The Enrollment APIs are based on the following principles:

When enrollment is done in one step, the CreateEnrollment can contain all the data and an additional flag (finalize) to indicate all data was collected.
During the process, the enrollment structure can be updated. Only the data that changed need to be transferred. Data not included is left unchanged on the server. In the following example, the biographic data is not changed.
Images can be passed by value or reference.
Existing standards are used whenever possible, for instance, the preferred image format for biometric data is ISO-19794. The underlying data should be of open mime types that offer good compression without loss of data (for example JPEG2000 for images).

8.3 Credential Management

These Credential Management APIs are a set of OpenAPI specifications exposed by the Identity Building Block to service identity credential requests by credential partners such as printing and QR code partners.

The Credential Management APIs are based on the following principles:

The credential request API is asynchronous for the identity holder i.e., the call to share credentials is responded with an event ID. Then the identity holder later uses the event ID to retrieve the details using the API '/events/{eventId}'.
The '/share-credential' API is used to convey the format of the credential information. The format allows the credential information to be masked/unmasked. The API also conveys the consent of the identity holder.
The API '/download/personalized-card' is used to download the identity card in PDF format.
Systems for Voter ID, Tax ID, Card printing etc. receive internal notifications from IDBB.
Wallet applications will receive the identity credentials as per pre-authorized flow.
The APIs '/block', '/unblock' and '/updateIdentity' can only be called by systems with administrative permissions given by the IDBB.

8.4 Subscription Management

The Subscription Management APIs follow the APIs from these standards - WebSub and WebHooks.

8.5 Administration Management

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

The tests for the Identity Building Block can be found in this GitHub repository.

API standards

The microservice interfaces are defined as per OPENAPI Ver3.0 standards.
For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.

8.1 Identity Usage

The Identity usage APIs are a set of OpenAPI specifications exposed by the Identity Building Block to other building blocks and applications for user verification.

The Identity usage APIs are based on the following principles:

Verification APIs are inspired by OpenID Connect protocol which simplifies integrations using pre-existing libraries
Only secure options in OpenID connect should be supported to ensure the user data is handled securely
All biometric capture for user verification should be done using Secure Biometrics Interface standards

Service Group: Client Management

Create OIDC Client Endpoint

API to add new open ID connect (OIDC) clients, it can be invoked by other modules which manages the relying parties / partners.

Each relying party can associate to one or multiple OIDC client Ids.

On create, OIDC client status will be by default set to "active".

POST/client-mgmt/oidc-client

Authorization

Body

requestTime*string

Current date and time when the request is sent

request*object

clientId*string

Unique OIDC client id (Case-Sensitive). If duplicates found, request will be rejected.

Example: "785b806d0e594657b05aabdb30fff8a4"

clientName*string

Name of OIDC client.

Example: "ABC Health Care"

relyingPartyId*string

Relying Party ID of the client. This will be passed on to authentications servers when KYC is fetched.

Note: Use the client Id as relyingPartyId if there is no separate concept of relying party in the ID authentication system.

Example: "bharathi-inc"

logoUri*string (uri)

Relying party logo URI which will used to display logo in OIDC login and permission pages.

redirectUris*array of string (uri)

Valid list of callback Uris of the relying party. When OIDC authorize API is called, any one Uri from this list should be sent as redirect_uri. authorization_code will be redirected to this Uri on successful authentication.

itemsstring (uri)

authContextRefs*array of enum

The Authentication Context Class Reference is case-sensitive string specifying a list of Authentication Context Class values that identifies the Authentication Context Class. Values that the authentication performed satisfied implying a Level Of Assurance.

itemsenum

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

publicKey*object

OIDC client's public key used to verify the client's private_key_jwt when OIDC token endpoint is invoked. This field will not be allowed to udpate later, if the private key is compromised, then new OIDC client to be created. Format : Json Web Key (JWK).

userClaims*array of enum

Allowed user info claims, that can be requested by OIDC client in the authorize API

itemsenum

namegiven_namefamily_namemiddle_namepreferred_usernamenicknamegenderbirthdateemailemail_verifiedphone_numberphone_number_verifiedpictureaddresslocalezoneinfo

grantTypes*array of enum

Form of Authorization Grant presented to token endpoint

itemsenum

authorization_code

clientAuthMethods*array of enum

Auth method supported for token endpoint. At present only "private_key_jwt" is supported.

itemsenum

private_key_jwt

Response

Body

responseTimestring

Date and time when the response is generated

responseobject

clientIdstring

Client id as provided in the request.

errorsarray of object

errorCodeenum

duplicate_client_idinvalid_public_keyinvalid_inputinvalid_client_idinvalid_client_nameinvalid_rp_idinvalid_claiminvalid_acrinvalid_uriinvalid_redirect_uriinvalid_grant_typeinvalid_client_authinvalid_request

errorMessagestring

Request

const response = await fetch('/client-mgmt/oidc-client', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "2011-10-05T14:48:00.000Z",
      "request": {
        "clientId": "e-health-service",
        "clientName": "Health Service",
        "relyingPartyId": "bharath-gov",
        "logoUri": "http://example.com",
        "redirectUris": [
          "http://example.com/login-success"
        ],
        "publicKey": {},
        "authContextRefs": [
          "idbb:acr:generated-code"
        ],
        "userClaims": [
          "name"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "clientAuthMethods": [
          "private_key_jwt"
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "clientId": "text"
  },
  "errors": [
    {
      "errorCode": "duplicate_client_id",
      "errorMessage": "text"
    }
  ]
}

Update OIDC Client Endpoint

API to update existing Open ID Connect (OIDC) client, it can be invoked by other modules which manages the relying parties / partners when there any updates on the fields accepted in this API.

Authentication and authorization is based on a valid JWT issued by a trusted IAM system including "update_oidc_client" scope.

PUT/client-mgmt/oidc-client/{client_id}

Authorization

Path parameters

client_id*string

Client Identifier

Example: "785b806d0e594657b05aabdb30fff8a4"

Body

requestTime*string

Current date and time when the request is sent

request*object

clientName*string

Name of the OIDC client.

Example: "ABC Health Care"

status*enum

Status of OIDC client.

activeinactive

logoUri*string (uri)

Relying party logo URI which will used to display logo in OIDC login and permissi

redirectUris*array of string (uri)

itemsstring (uri)

userClaims*array of enum

Allowed user info claims, that can be requested by OIDC client in the authorize API

itemsenum

namegiven_namefamily_namemiddle_namepreferred_usernamenicknamegenderbirthdateemailemail_verifiedphone_numberphone_number_verifiedpictureaddresslocalezoneinfo

authContextRefs*array of enum

itemsenum

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

grantTypes*array of enum

Form of Authorization Grant presented to token endpoint.

itemsenum

authorization_code

clientAuthMethods*array of enum

Auth method supported for token endpoint. At present only "private_key_jwt" is supported.

itemsenum

private_key_jwt

Response

Body

responseTimestring

Date and time when the response is generated

responseobject

clientId*string

OIDC client identifier.

errorsarray of object

List of Errors in case of request validation / processing failure in IDBB server. When request processing is fully successful, this array will be empty.

errorCodeenum

invalid_client_idinvalid_client_nameinvalid_claiminvalid_acrinvalid_uriinvalid_redirect_uriinvalid_grant_typeinvalid_client_authinvalid_request

errorMessagestring

Request

const response = await fetch('/client-mgmt/oidc-client/{client_id}', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "2022-09-22T08:03:45.000Z",
      "request": {
        "clientName": "Health Service",
        "status": "active",
        "logoUri": "http://example.com",
        "redirectUris": [
          "http://example.com/login-success"
        ],
        "userClaims": [
          "name"
        ],
        "authContextRefs": [
          "idbb:acr:generated-code"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "clientAuthMethods": [
          "private_key_jwt"
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "clientId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_client_id",
      "errorMessage": "text"
    }
  ]
}

Authorization Endpoint

This is the authorize endpoint of Open ID Connect (OIDC). The relying party applications will do a browser redirect to this endpoint with all required details passed as query parameters.

This endpoint will respond with a HTML page / JS application to be loaded in the browser.

All the validations on the query parameter values will be performed, in case of any failures respective error message will be sent along with browser redirection back to relying party application.

GET/authorize

Query parameters

scope*enum

Specifies what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. OpenID Connect requests MUST contain the OpenID scope value.

openid profileopenidprofileemailaddressphoneoffline_access

response_type*enum

The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".

code

client_id*string

Valid OAuth 2.0 Client Identifier in the Authorization Server.

redirect_uri*string (uri)

Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.

statestring

Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

noncestring

String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.

displayenum

ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.

pagepopuptouchwap

promptenum

Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.

Example: "consent"

noneloginconsentselect_account

max_agenumber

Maximum Authentication Age. This specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated by the OP. If the elapsed time is greater than this value, then the OP MUST attempt to actively re-authenticate the end user. The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter. When max_age is used, the ID Token returned MUST include an auth_time claim value.

ui_localesstring

End user's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

acr_valuesenum

Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

claims_localesstring

End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

claimsstring

This parameter is used to request specific claims to be returned. The value is a JSON object listing the requested claims. The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON.

Response

Loads IDBB UI application in browser for interacting with user for Login process

Request

const response = await fetch('/authorize?scope=openid+profile&response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Token Endpoint

Once the client / relying party application receives the authorization code through redirect, this OIDC complaint endpoint will be called from the relying party backend application to get the ID Token and Access Token.

The only supported client authentication method : private_key_jwt
ClientAssertion is a signed JWT with client's private key, corresponding public key should be shared with IDBB during the OIDC client creation process.
clientAssertion JWT payload must be as below:

The JWT MUST contain the following REQUIRED Claim Values and MAY contain few additional OPTIONAL Claim Values:

iss* (Issuer): This MUST contain the client_id of the OIDC / OAuth Client.

sub* (Subject): This MUST contain the client_id of the OIDC / OAuth Client.

aud* (Audience): Value that identifies the IDBB server as an intended audience. The IDBB server MUST verify that it is an intended audience for the token. The audience SHOULD be the URL of the IDBB's token endpoint.

exp* (Expiration): Time on or after which the ID token MUST NOT be accepted for processing.

iat*: Time at which the JWT was issued.

Note: The Client Assertion JWT can contain other Claims. Any Claims used that are not understood WILL be ignored.

POST/oauth/token

Body

grant_type*enum

Authorization code grant type.

authorization_code

code*string

Authorization code, sent as query param in the client's redirect URI.

client_id*string

Client Id of the OIDC client.

client_assertion_type*enum

Type of the client assertion part of this request.

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion*string

Private key signed JWT, This JWT payload structure is defined above as part of request description.

redirect_uri*string

Valid client redirect_uri. Must be same as the one sent in the authorize call.

Response

Headers

Cache-Controlenum

no-store

Pragmaenum

no-cache

Body

id_token*string

Identity token in JWT format. Will have the below claims in the payload.

access_token*string

The access token in JWT format. This token will be used to call the UserInfo endpoint. Relying party application should handle access token as opaque.

token_type*enum

The type of the access token, set to Bearer

Bearer

expires_in*number (duration)

The lifetime of the access token, in seconds.

Request

const response = await fetch('/oauth/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "grant_type": "authorization_code",
      "code": "text",
      "client_id": "text",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "text",
      "redirect_uri": "text"
    }),
});
const data = await response.json();

Response

{
  "id_token": "text",
  "access_token": "text",
  "token_type": "Bearer",
  "expires_in": 0
}

UserInfo Endpoint

Once the access token is received via the token endpoint, relying party backend application can call this OIDC compliant endpoint to request for the user claims.

Consented user claims will be returned as a JWT. This JWT will be a nested JWT which is signed using JWS and then encrypted using JWE.

Example: Assuming the below are the requested claims by the relying party

name : { "essential" : true }

phone: { "essential" : true }

Response 1: When consent is provided for both name and phone number:

{ "name" : "John Doe", "phone" : "033456743" }

Response 2: When consent is provided for only name:

{ "name" : "John Doe" }

Response 3: When Claims are requested with claims_locales : "en fr"

{ "name#en" : "John Doe", "name#fr" : "Jean Doe", "phone" : "033456743" }

Supported User Info Claims

GET/oidc/userinfo

Authorization

Response

Body

string (jwt)

The response is signed and then encrypted, with the result being a Nested JWT. Signed using the IDBB's private key. Signed full JWT will then be encrypted using OIDC client's public key.

Request

const response = await fetch('/oidc/userinfo', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

text

JSON Web Key Set Endpoint

Endpoint to fetch all the public keys of the IDBB server. Returns public key set in the JWKS format.

GET/.well-known/jwks.json

Response

Body

keysarray of object

kid*string

The certificate's Key ID

use*enum

How the Key is used. Valid value: sig

sig

kty*enum

Cryptographic algorithm family for the certificate's Key pair. Valid value: RSA

RSA

e*string

RSA Key value (exponent) for Key blinding

n*string

RSA modulus value

x5t#S256*string

SHA-256 thumbprint of the certificate.

x5c*array of string

Certificate to validate the Oauth server trust.

itemsstring

exp*string (date-time)

Expire datetime of the key. Given in ISO format.

Example: "2026-02-05T13:43:07.979Z"

Request

const response = await fetch('/.well-known/jwks.json', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "keys": [
    {
      "kid": "text",
      "use": "sig",
      "kty": "RSA",
      "e": "text",
      "n": "text",
      "x5t#S256": "text",
      "x5c": [
        "text"
      ],
      "exp": "2026-02-05T13:43:07.979Z"
    }
  ]
}

Configuration Endpoint

This endpoint is only for facilitating the OIDC provider details in a standard way.

Reference: https://openid.net/specs/openid-connect-discovery-1_0.html

GET/.well-known/openid-configuration

Response

Body

issuer*string

URL using the https scheme with no query or fragment component that the RP asserts as its Issuer Identifier. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.

authorization_endpoint*string

URL of the OAuth 2.0 Authorization Endpoint.

token_endpoint*string

URL of the OAuth 2.0 Token Endpoint.

userinfo_endpoint*string

URL of the OP's UserInfo Endpoint.

jwks_uri*string

URL of the OP's JSON Web Key Set [JWK] document.

registration_endpoint*string

URL of Client Registration Endpoint.

scopes_supported*array of enum

JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports.

itemsenum

openid

response_types_supported*array of enum

JSON array containing a list of the OAuth 2.0 response_type values that this OP supports.

itemsenum

code

acr_values_supportedarray of any

JSON array containing a list of the Authentication Context Class References that IDP supports.

itemsany

userinfo_signing_alg_values_supportedarray of any

JSON array containing a list of the JWS [JWS] signing algorithms.

itemsany

userinfo_encryption_alg_values_supportedarray of any

JSON array containing a list of the JWE [JWE] encryption algorithms.

itemsany

userinfo_encryption_enc_values_supportedarray of any

JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT.

itemsany

token_endpoint_auth_methods_supportedarray of enum

JSON array containing a list of Client Authentication methods supported by this Token Endpoint.

itemsenum

private_key_jwt

display_values_supportedarray of any

JSON array containing a list of the display parameter values that the OpenID Provider supports.

itemsany

claim_types_supportedarray of enum

JSON array containing a list of the Claim Types that the OpenID Provider supports.

itemsenum

normalaggregateddistributed

claims_supportedarray of string

JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for.

itemsstring

claims_locales_supportedarray of string

Languages and scripts supported for values in Claims being returned.

itemsstring

ui_locales_supportedarray of string

Languages and scripts supported for the user interface.

itemsstring

response_modes_supportedarray of enum

Mechanism to be used for returning parameters from the Authorization Endpoint.

itemsenum

query

token_endpoint_auth_signing_alg_values_supportedarray of enum

itemsenum

RS256

id_token_signing_alg_values_supportedarray of enum

itemsenum

RS256

Request

const response = await fetch('/.well-known/openid-configuration', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "issuer": "text",
  "authorization_endpoint": "text",
  "token_endpoint": "text",
  "userinfo_endpoint": "text",
  "jwks_uri": "text",
  "registration_endpoint": "text",
  "scopes_supported": [
    "openid"
  ],
  "response_types_supported": [
    "code"
  ],
  "acr_values_supported": [],
  "userinfo_signing_alg_values_supported": [],
  "userinfo_encryption_alg_values_supported": [],
  "userinfo_encryption_enc_values_supported": [],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "display_values_supported": [],
  "claim_types_supported": [
    "normal"
  ],
  "claims_supported": [
    "text"
  ],
  "claims_locales_supported": [
    "text"
  ],
  "ui_locales_supported": [
    "text"
  ],
  "response_modes_supported": [
    "query"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "RS256"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.

Generate Link Code endpoint

Generate link code request is raised from IDBB UI application.

UI application creates a deeplink with this link-code as parameter.
This deeplink is embedded in a Machine-readable-code (like QR code) and the same is rendered in the UI.
End user scans this machine-readable-code to open wallet app.
On open of wallet-app, wallet-app invokes /link-transaction endpoint.
In the UI application, once machine-readable-code is rendered, at the same time /link-status endpoint is invoked as a long polling request.

POST/linked-authorization/link-code

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

TransactionId that associates the current transaction / session with the relying party redirection. IDBB backend application should be able to maintain this association with respective to the transaction Id.

Response

Body

responseTimestring

responseobject

transactionIdstring

The same transactionId passed as part of the request.

linkCodestring

Unique random string mapped to this transactionId.

expireDateTimestring

Expire date time (ISO format) for the generated linkCode. After this date time linkCode in this request is not valid.

errorsarray of object

errorCodeenum

invalid_transaction_idlink_code_gen_failedinvalid_transactioninvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-code', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "transactionId": "text",
    "linkCode": "text",
    "expireDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Link status endpoint

The link status endpoint is invoked from IDBB UI application.

Checks the status of link code and will return the status as LINKED once the /link-transaction endpoint is called from wallet application.

POST/linked-authorization/link-status

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

This is the same transactionId sent in the /link-code request

linkCode*string

This is same linkCode returned in the generate-link-code response.

Response

Body

responseTImestring

responseobject

transactionIdstring

This is the same transactionId as sent in the request.

linkStatusenum

Link status of the linkCode passed in the request.

LINKED

linkedDateTimestring

Epoch in milliseconds at which the wallet-app acknowledged the link-code.

errorsarray of object

errorCodeenum

invalid_transaction_idinvalid_link_coderesponse_timeoutunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-status', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text",
        "linkCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTIme": "text",
  "response": {
    "transactionId": "text",
    "linkStatus": "LINKED",
    "linkedDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Link authorization code endpoint

Link authorization code endpoint is invoked from UI application.

This is a Long polling request to IDBB backend.
validates the transactionId
validates the linkCode if its LINKED.
checks the cache to see if the auth-code is generated, if yes returns the response.
If the auth-code is not yet generated, polling request waits for the configured time.
On successful response, IDBB UI should redirect to the provided redirectUri with auth-code or error details.

POST/linked-authorization/link-auth-code

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

This is the same transactionId sent in the /link-code request.

linkedCode*string

linkCode for which status is already received as LINKED.

Response

Body

responseTimestring

responseobject

codestring

Authorization code. Required to obtain the ID token and / or access token from the /token endpoint.

redirectUristring

Client's validated redirect URI.

statestring

The echoed state value, used to maintain state between the request and the callback

noncestring

The echoed nonce value, if one was passed with the request. Clients must validate the value before proceeding.

errorsarray

Request

const response = await fetch('/linked-authorization/link-auth-code', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text",
        "linkedCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "code": "text",
    "redirectUri": "text",
    "state": "text",
    "nonce": "text"
  }
}

Link Transaction endpoint

The link transaction endpoint is invoked from Wallet-app.

Validates the link-code and its expiry and generates the linkTransactionId. This linkTransactionId is linked to transactionId used in the /link-code endpoint.
Returns the auth-factors, clientName, logoUrl, User claims, authorize scopes along with linkTransactionId.

Note: Wallet-app will hereafter address the transaction with this linkTransactionId for the /authenticate and /consent endpoints.

POST/linked-authorization/link-transaction

Body

requestTime*string

request*object

linkCode*string

Link code as received by the wallet-app from the QR code scanning.

Response

Body

responseTimestring

responseobject

linkTransactionIdstring

Unique link-transaction-id.

clientNamestring

Registered name of the OIDC client.

logoUrlstring

Registered OIDC client Logo URL.

authorizeScopesarray of string

List of requested scopes to be permitted by the end user.

itemsstring

essentialClaimsarray of string

List of client request mandatory claim names.

itemsstring

voluntaryClaimsarray of string

List of client request optional claim names.

itemsstring

authFactorsarray of array of AuthFactor

Auth factors defines the authentication modes that can be used to veifiy the user. More than one authFactor may be resolved or combination of auth factors. Precedence of authFactors is based on its order

type*enum

Name of the authentication method

PINOTPL1-bio-deviceWallet

countinteger

Applicable for biometric based authentication, number of bio segments to be captured for authentication.

bioSubTypesarray of string

Applicable for biometric based authentication. Can be more specific about which bio segments should be captured.

itemsstring

configsobject

errorsarray of object

errorCodeenum

invalid_link_codeinvalid_transactioninvalid_client_idunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-transaction', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkTransactionId": "text",
    "clientName": "text",
    "logoUrl": "text",
    "authorizeScopes": [
      "text"
    ],
    "essentialClaims": [
      "text"
    ],
    "voluntaryClaims": [
      "text"
    ],
    "authFactors": [
      [
        {
          "type": "PIN",
          "bioSubTypes": [
            "text"
          ]
        }
      ]
    ]
  },
  "errors": [
    {
      "errorCode": "invalid_link_code",
      "errorMessage": "text"
    }
  ]
}

Linked Authentication Endpoint

Once end user provides the user identifier (UIN/VID) and all the required auth challenge to the Wallet-app, this endpoint will be invoked from wallet-app.

Supported auth-challenge depends on the integrated IDBB implementation.

Validates linkedTransactionId.
Validates null / empty individualId.

On Authentication Success: Only linkTransactionId is returned in the below response without any errors.

On Authentication Failure: Error list will be returned.

POST/linked-authorization/authenticate

Body

requestTime*string

Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

request*object

linkedTransactionId*string

This is the same transactionId received from /link-transaction endpoint

individualId*string

User identifier (UIN/VID).

challengeList*array of AuthChallenge

Authentication Challenge.

authFactorType*enum

Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).

OTPBIOPINWLA

challenge*string

Actual challenge as string.

format*enum

Format of the challenge provided.

alpha-numericjwtencoded-jsonnumber

Response

Body

responseTimestring

responseobject

linkedTransactionIdstring

This is the same transactionId received from /link-transaction endpoint.

errorsarray of object

List of Errors in case of request validation / processing failure in IDBB server.

errorCodeenum

invalid_transaction_idinvalid_transactioninvalid_identifierinvalid_no_of_challengesauth_failedunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/authenticate', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkedTransactionId": "text",
        "individualId": "text",
        "challengeList": [
          {
            "authFactorType": "OTP",
            "challenge": "text",
            "format": "alpha-numeric"
          }
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkedTransactionId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Once the authentication is successful and user permission is obtained, this endpoint will be invoked by the wallet app to send the accepted user claims and permitted scopes.

Validates linkedTransactionId.
Validate accepted claims and permitted scopes in the request.
If valid, stores the accepted claims and permitted scopes in the datastore.

POST/linked-authorization/consent

Body

requestTime*string

Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

request*object

linkedTransactionId*string

This is the same transactionId received from /link-transaction endpoint.

permittedAuthorizeScopesarray of string

List of permitted scopes by end-user.

itemsstring

acceptedClaimsarray of string

List of accepted essential and voluntary claims by end-user.

itemsstring

Response

Body

responseTimestring

responseobject

linkedTransactionIdstring

This is the same transactionId received from /link-transaction endpoint.

errorsarray of object

errorCodeenum

invalid_transaction_idinvalid_transactioninvalid_accepted_claiminvalid_permitted_scopeinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/consent', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkedTransactionId": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkedTransactionId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Wallet Binding Endpoint (Draft)

Wallet binding endpoint is invoked by Wallet's backend server.

Action will be initiated from wallet-app with authChallenge by user.
Wallet backend server will receive the authChallenge, create this request and send to IDBB to complete the binding process.
Binded walletUserId (WUID) is returned with IDBB signed certificate.

Note: Binding entry uniqueness is combination of these 3 values -> (PSUT, public-key, auth-factor-type)

POST/wallet-binding

Authorization

Header parameters

PARTNER-ID*string

An identifier for the partner.

PARTNER-API-KEY*string

An API key provided to the partner for authentication purposes.

Body

requestTime*string

request*object

individualId*string

User Id (UIN/VID).

authFactorType*string

Auth factor type to be binded for the provided key.

format*string

Format of the auth factor type supported in the wallet app.This is not stored, this value is only validated to check if its a supported format in the IDBB implementation.

challengeList*array of AuthChallenge

authFactorType*enum

Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).

OTPBIOPINWLA

challenge*string

Actual challenge as string.

format*enum

Format of the challenge provided.

alpha-numericjwtencoded-jsonnumber

publicKey*object

key to be binded in JWK format.

Response

Body

responseTime*string

responseobject

walletUserIdstring

Unique identifier given to public-key and partner specific userId mapping.

certificatestring

Key binder signed certificate.

expireDateTimestring

Expire date time of the signed certificate.

errorsarray of object

errorCodeenum

unsupported_challenge_formatkey_binding_failedinvalid_public_keyinvalid_auth_challengeduplicate_public_keyinvalid_request

errorMessagestring

Request

const response = await fetch('/wallet-binding', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "PARTNER-ID": "text",
      "PARTNER-API-KEY": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "individualId": "text",
        "authFactorType": "text",
        "format": "text",
        "challengeList": [
          {
            "authFactorType": "OTP",
            "challenge": "text",
            "format": "alpha-numeric"
          }
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "walletUserId": "text",
    "certificate": "text",
    "expireDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "unsupported_challenge_format",
      "errorMessage": "text"
    }
  ]
}

Detailed API schemas written in YAML that define REST API endpoints for each of the services mentioned above are available on GitHub located at the Identity-Provider YAML.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.

8.2 Identity Management

The Enrollment APIs are a set of OpenAPI specifications exposed by the Identity Building Block ‘Enrollment Server’ service to any enrollment client.

The Enrollment APIs are based on the following principles:

When enrollment is done in one step, the CreateEnrollment can contain all the data and an additional flag (finalize) to indicate all data was collected.
During the process, the enrollment structure can be updated. Only the data that changed need to be transferred. Data not included is left unchanged on the server. In the following example, the biographic data is not changed.
Images can be passed by value or reference.
Existing standards are used whenever possible, for instance, the preferred image format for biometric data is ISO-19794. The underlying data should be of open mime types that offer good compression without loss of data (for example JPEG2000 for images).

8.3 Credential Management

The Credential Management APIs are based on the following principles:

The credential request API is asynchronous for the identity holder i.e., the call to share credentials is responded with an event ID. Then the identity holder later uses the event ID to retrieve the details using the API '/events/{eventId}'.
The '/share-credential' API is used to convey the format of the credential information. The format allows the credential information to be masked/unmasked. The API also conveys the consent of the identity holder.
The API '/download/personalized-card' is used to download the identity card in PDF format.
Systems for Voter ID, Tax ID, Card printing etc. receive internal notifications from IDBB.
Wallet applications will receive the identity credentials as per pre-authorized flow.
The APIs '/block', '/unblock' and '/updateIdentity' can only be called by systems with administrative permissions given by the IDBB.

Format for sharing identity credentials with an identity partner

POST/share-credential

Body

idstring

id to hit API

requestobject

Request body to share credential

partnerIdstring

Id to which credentials will be shared

sharableAttributesarray of object

attributeNamestring

Example: dateOfBirth

formatstring

Example: DDMMYYYY

isMaskedboolean

boolean value whether to mask or not

purposestring

Sharing Credential with Print Partner

Pattern: ^[\\r\\nA-Za-z0-9 .,'\\-]+$

consentstring

consent whether Accepted or denied

requesttimestring

2021-10-19T17:01:59.538Z

versionstring

Example: 1.0

Response

EventId generated successfully.

Headers

eventIdstring

Body

idstring

id to share credential Ex:- resident.share.credential

versionstring

version to share credential

responsetimestring

local timestamp Ex:- 2022-06-23T12:00:40.326Z

metadataobject

responseobject

statusstring

status of share credential API Ex:-Success

errorsobject

Errors will be shown with error code and value

Request

Response

Get the status by eventID

GET/events/{eventId}?language=LANGCODE

Authorization

Path parameters

eventId*integer

Event ID to get the status

Query parameters

language*string

Language Code in 3 letters. Example- eng

Response

Body

idstring

id of get event status API

versionstring

version of API

responseobject

eventIdstring

Randomly generated 16 digit number

eventTypestring

Type of event like Authentication type

eventStatusstring

Status of request whether succss, failure or in-progress

individualIdstring

UIN/Vid of logged in user

summarystring

Having short summary about the event id.

timestampstring

local timestamp

infoobject

Info for multiple attributes

purposestring

purpose to share credential like sharing to some other parters

applicantNamestring

name of applicant

partnerIdstring

parter id to which we want to share credential

partnerLogostring

Logo of partner if any

partnerNamestring

name of partner

paymentStatusstring

status of payment

partnerTransactionIdstring

unique transaction id of payment if any

deliveryAddressstring

delieveryAddress of user in case of order physical card.

authenticationModestring

mode of authentication like OTP

vidTypestring

type of vid like perpetual which means permanent , one-time(which means it can be used only once)

vidstring

virtual id that is created with the help of uin

attributeListstring

list of attributes like firstName, email

downloadCardLinkstring

direct link to download

orderTrackingLinkstring

direct link to track order status

trackingIdstring

id to track order

requestTimestring

timestamp when API executes

Request

Response

Download the personalized UIN Card

POST/download/personalized-card

Authorization

Body

idstring

id for downloading card

versionstring

version of API

requesttimestring

timestamp when we hit API

requestobject

htmlstring

html input of download personalized card which will be later converted to PDF

Response

OK - The PDF Bytes

Headers

eventIdstring

Request

Response

Update UIN request raised by the resident/citizen

POST/update-uin

Authorization

Body

idstring

id to hit update uin API.

versionstring

version of API

requestTimestring

timestamp when we get resposne.

requestobject

transactionIDstring

transactionId will be shown that is used to send otp.

individualIdstring

uin/vid which is used to send otp for updating uin

individualIdTypestring

type of individual id like uin/vid

otpstring

otp to verify mobile number

identityJsonstring

base 64 encoded identity value that we want to update.

documentsarray of object

namestring

valuestring

Response

OK, update is successful.

Body

idstring

mosip.resident.updateuin

versionstring

1.0

responsetimestring

2024-03-21T09:14:42.537Z

response*object

Give response such as Registration id and 1 message like Notification has been sent to the provided contact detail(s)

errorsarray of ServiceError (object)

errorCodestring

messagestring

Request

Response

Get the status by eventID

GET/service-history/{langCode}

Authorization

Path parameters

langCode*string

Language Code in 3 letters. Example- eng

Query parameters

fromDate*string

Start date of the request inclusive; the default date will be the 1st of January of that year

pageFetchstring

integer greater than 0, default is 10

pageStartstring

integer starting from 0, default is 0

searchTextstring

This will be used to look for Event Id- string greater than 0 but not more than 30; >= 0 characters; <= 30 characters

serviceTypestring

The service type in general. It can map to different request types. Possible values: AUTHENTICATION_REQUEST, SERVICE_REQUEST,DATA_UPDATE_REQUEST,ID_MANAGEMENT_REQUEST,DATA_SHARE_REQUEST,ALL; default is ALL

sortTypestring

ASC/DESC, default is ASC

statusFilterstring

Comma separated service types status code- optional. This can be one of - ALL,SUCCESS,IN_PROGRESS,FAILED

toDatestring

End date of the request inclusive; the default date will be the date on which this transaction is being done (date today

Header parameters

locale*string

Locale based on Language and country.Used in date time formatting. Ex. en-US

time-zone-offset*string

Used in time conversion per the client on any timestamps returned in the response. Ex. -330 - for India

Response

Body

idstring

id to get service history API

versionstring

version of service history API

errorsarray of object

errorCodestring

errorMessagestring

responseobject

pageNointeger

starting number of page from where history needs to be fetched.

pageSizeinteger

number of pages

totalItemsinteger

total items across all pages

totalPagesinteger

total number of pages

dataarray of object

eventIdstring

Random 16 digits eventId

eventDescriptionstring

details of events

eventStatusstring

status of event

timeStampstring

timestamp of response

requestTypestring

type of request

responseTimestring

Request

Response

Activate/Deactivate UIN

PATCH/updateIdentity

Body

idstring

Example - govstack.updateIdentity

versionstring

requesttimestring

timestamp when API executes

metaDataobject

requestobject

statusstring

status of updateIdentity APi

identityobject

identity which user wants to update

documentsarray of object

categorystring

cateogory like proof of resident

valuestring

document value like pdf content

verifiedAttributesarray of object

attributeStringstring

registrationIdstring

unique id created while registring uin

uinstring

unique value for each individual

Response

UIN activation status successfully updated

Body

idstring

Example - govstack.updateIdentity

versionstring

responsetimestring

timestamp

metaDataobject

responseobject

statusstring

status of API

identityobject

identity that user wants to update

documentsarray of object

categorystring

cateogory like proof of resident

valuestring

document value like pdf content

verifiedAttributesarray of object

attributeStringstring

errorsarray of object

errorCodestring

errorMessagestring

Request

Response

Command to be used by administrators to unblock UIN

POST/unblock

Body

idstring

id to hit API

versionstring

version of API

requesttimestring

timestamp when API executed

metadataobject

requestobject

idstring

idTypestring

statusstring

expiryTimestampstring

Response

UIN unblocked successfully.

Body

idstring

id to hit API

versionstring

version of API

responsetimestring

timestamp when API executed

metadataobject

responseobject

idstring

unique id

idTypestring

type of id like uin/vid

statusstring

status of API

expiryTimestampstring

timestamp when it will expire

errorsarray of object

errorCodestring

messagestring

Request

Response

Command to be used by administrators to block UIN

POST/block

Body

idstring

id to hit API

versionstring

version of API

requesttimestring

timestamp when API executed

metadataobject

requestobject

idstring

idTypestring

statusstring

expiryTimestampstring

Response

UIN blocked successfully.

Body

idstring

id to hit API

versionstring

version of API

responsetimestring

timestamp when API executed

metadataobject

responseobject

idstring

unique id

idTypestring

type of id like uin/vid

statusstring

status of API

expiryTimestampstring

timestamp when it will expire

errorsarray of object

errorCodestring

messagestring

Request

Response

8.4 Subscription Management

The Subscription Management APIs follow the APIs from these standards - WebSub and WebHooks.

8.5 Administration Management

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.

Update UIN request raised by the resident/citizen

POST/update-uin

Authorization

Body

idstring

id to hit update uin API.

versionstring

version of API

requestTimestring

timestamp when we get resposne.

requestobject

transactionIDstring

transactionId will be shown that is used to send otp.

individualIdstring

uin/vid which is used to send otp for updating uin

individualIdTypestring

type of individual id like uin/vid

otpstring

otp to verify mobile number

identityJsonstring

base 64 encoded identity value that we want to update.

documentsarray of object

namestring

valuestring

Response

OK, update is successful.

Body

idstring

mosip.resident.updateuin

versionstring

1.0

responsetimestring

2024-03-21T09:14:42.537Z

response*object

Give response such as Registration id and 1 message like Notification has been sent to the provided contact detail(s)

errorsarray of ServiceError (object)

errorCodestring

messagestring

Request

Response

Get the status by eventID

GET/service-history/{langCode}

Authorization

Path parameters

langCode*string

Language Code in 3 letters. Example- eng

Query parameters

fromDate*string

Start date of the request inclusive; the default date will be the 1st of January of that year

pageFetchstring

integer greater than 0, default is 10

pageStartstring

integer starting from 0, default is 0

searchTextstring

This will be used to look for Event Id- string greater than 0 but not more than 30; >= 0 characters; <= 30 characters

serviceTypestring

sortTypestring

ASC/DESC, default is ASC

statusFilterstring

Comma separated service types status code- optional. This can be one of - ALL,SUCCESS,IN_PROGRESS,FAILED

toDatestring

End date of the request inclusive; the default date will be the date on which this transaction is being done (date today

Header parameters

locale*string

Locale based on Language and country.Used in date time formatting. Ex. en-US

time-zone-offset*string

Used in time conversion per the client on any timestamps returned in the response. Ex. -330 - for India

Response

Body

idstring

id to get service history API

versionstring

version of service history API

errorsarray of object

errorCodestring

errorMessagestring

responseobject

pageNointeger

starting number of page from where history needs to be fetched.

pageSizeinteger

number of pages

totalItemsinteger

total items across all pages

totalPagesinteger

total number of pages

dataarray of object

eventIdstring

Random 16 digits eventId

eventDescriptionstring

details of events

eventStatusstring

status of event

timeStampstring

timestamp of response

requestTypestring

type of request

responseTimestring

Request

Response

Format for sharing identity credentials with an identity partner

POST/share-credential

Body

idstring

id to hit API

requestobject

Request body to share credential

partnerIdstring

Id to which credentials will be shared

sharableAttributesarray of object

attributeNamestring

Example: dateOfBirth

formatstring

Example: DDMMYYYY

isMaskedboolean

boolean value whether to mask or not

purposestring

Sharing Credential with Print Partner

Pattern: ^[\\r\\nA-Za-z0-9 .,'\\-]+$

consentstring

consent whether Accepted or denied

requesttimestring

2021-10-19T17:01:59.538Z

versionstring

Example: 1.0

Response

EventId generated successfully.

Headers

eventIdstring

Body

idstring

id to share credential Ex:- resident.share.credential

versionstring

version to share credential

responsetimestring

local timestamp Ex:- 2022-06-23T12:00:40.326Z

metadataobject

responseobject

statusstring

status of share credential API Ex:-Success

errorsobject

Errors will be shown with error code and value

Request

Response

Activate/Deactivate UIN

PATCH/updateIdentity

Body

idstring

Example - govstack.updateIdentity

versionstring

requesttimestring

timestamp when API executes

metaDataobject

requestobject

statusstring

status of updateIdentity APi

identityobject

identity which user wants to update

documentsarray of object

categorystring

cateogory like proof of resident

valuestring

document value like pdf content

verifiedAttributesarray of object

attributeStringstring

registrationIdstring

unique id created while registring uin

uinstring

unique value for each individual

Response

UIN activation status successfully updated

Body

idstring

Example - govstack.updateIdentity

versionstring

responsetimestring

timestamp

metaDataobject

responseobject

statusstring

status of API

identityobject

identity that user wants to update

documentsarray of object

categorystring

cateogory like proof of resident

valuestring

document value like pdf content

verifiedAttributesarray of object

attributeStringstring

errorsarray of object

errorCodestring

errorMessagestring

Request

Response

Get the status by eventID

GET/events/{eventId}?language=LANGCODE

Authorization

Path parameters

eventId*integer

Event ID to get the status

Query parameters

language*string

Language Code in 3 letters. Example- eng

Response

Body

idstring

id of get event status API

versionstring

version of API

responseobject

eventIdstring

Randomly generated 16 digit number

eventTypestring

Type of event like Authentication type

eventStatusstring

Status of request whether succss, failure or in-progress

individualIdstring

UIN/Vid of logged in user

summarystring

Having short summary about the event id.

timestampstring

local timestamp

infoobject

Info for multiple attributes

purposestring

purpose to share credential like sharing to some other parters

applicantNamestring

name of applicant

partnerIdstring

parter id to which we want to share credential

partnerLogostring

Logo of partner if any

partnerNamestring

name of partner

paymentStatusstring

status of payment

partnerTransactionIdstring

unique transaction id of payment if any

deliveryAddressstring

delieveryAddress of user in case of order physical card.

authenticationModestring

mode of authentication like OTP

vidTypestring

type of vid like perpetual which means permanent , one-time(which means it can be used only once)

vidstring

virtual id that is created with the help of uin

attributeListstring

list of attributes like firstName, email

downloadCardLinkstring

direct link to download

orderTrackingLinkstring

direct link to track order status

trackingIdstring

id to track order

requestTimestring

timestamp when API executes

Request

Response

Authorization Endpoint

This is the authorize endpoint of Open ID Connect (OIDC). The relying party applications will do a browser redirect to this endpoint with all required details passed as query parameters.

This endpoint will respond with a HTML page / JS application to be loaded in the browser.

All the validations on the query parameter values will be performed, in case of any failures respective error message will be sent along with browser redirection back to relying party application.

GET/authorize

Query parameters

scope*enum

openid profileopenidprofileemailaddressphoneoffline_access

response_type*enum

The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".

code

client_id*string

Valid OAuth 2.0 Client Identifier in the Authorization Server.

redirect_uri*string (uri)

Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.

statestring

noncestring

String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.

displayenum

ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.

pagepopuptouchwap

promptenum

Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.

Example: "consent"

noneloginconsentselect_account

max_agenumber

ui_localesstring

acr_valuesenum

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

claims_localesstring

claimsstring

Response

Loads IDBB UI application in browser for interacting with user for Login process

Request

const response = await fetch('/authorize?scope=openid+profile&response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

UserInfo Endpoint

Once the access token is received via the token endpoint, relying party backend application can call this OIDC compliant endpoint to request for the user claims.

Consented user claims will be returned as a JWT. This JWT will be a nested JWT which is signed using JWS and then encrypted using JWE.

Example: Assuming the below are the requested claims by the relying party

name : { "essential" : true }

phone: { "essential" : true }

Response 1: When consent is provided for both name and phone number:

{ "name" : "John Doe", "phone" : "033456743" }

Response 2: When consent is provided for only name:

{ "name" : "John Doe" }

Response 3: When Claims are requested with claims_locales : "en fr"

{ "name#en" : "John Doe", "name#fr" : "Jean Doe", "phone" : "033456743" }

Supported User Info Claims

GET/oidc/userinfo

Authorization

Response

Body

string (jwt)

The response is signed and then encrypted, with the result being a Nested JWT. Signed using the IDBB's private key. Signed full JWT will then be encrypted using OIDC client's public key.

Request

const response = await fetch('/oidc/userinfo', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

text

JSON Web Key Set Endpoint

Endpoint to fetch all the public keys of the IDBB server. Returns public key set in the JWKS format.

GET/.well-known/jwks.json

Response

Body

keysarray of object

kid*string

The certificate's Key ID

use*enum

How the Key is used. Valid value: sig

sig

kty*enum

Cryptographic algorithm family for the certificate's Key pair. Valid value: RSA

RSA

e*string

RSA Key value (exponent) for Key blinding

n*string

RSA modulus value

x5t#S256*string

SHA-256 thumbprint of the certificate.

x5c*array of string

Certificate to validate the Oauth server trust.

itemsstring

exp*string (date-time)

Expire datetime of the key. Given in ISO format.

Example: "2026-02-05T13:43:07.979Z"

Request

const response = await fetch('/.well-known/jwks.json', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "keys": [
    {
      "kid": "text",
      "use": "sig",
      "kty": "RSA",
      "e": "text",
      "n": "text",
      "x5t#S256": "text",
      "x5c": [
        "text"
      ],
      "exp": "2026-02-05T13:43:07.979Z"
    }
  ]
}

Once the authentication is successful and user permission is obtained, this endpoint will be invoked by the wallet app to send the accepted user claims and permitted scopes.

Validates linkedTransactionId.
Validate accepted claims and permitted scopes in the request.
If valid, stores the accepted claims and permitted scopes in the datastore.

POST/linked-authorization/consent

Body

requestTime*string

Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

request*object

linkedTransactionId*string

This is the same transactionId received from /link-transaction endpoint.

permittedAuthorizeScopesarray of string

List of permitted scopes by end-user.

itemsstring

acceptedClaimsarray of string

List of accepted essential and voluntary claims by end-user.

itemsstring

Response

Body

responseTimestring

responseobject

linkedTransactionIdstring

This is the same transactionId received from /link-transaction endpoint.

errorsarray of object

errorCodeenum

invalid_transaction_idinvalid_transactioninvalid_accepted_claiminvalid_permitted_scopeinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/consent', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkedTransactionId": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkedTransactionId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Generate Link Code endpoint

Generate link code request is raised from IDBB UI application.

UI application creates a deeplink with this link-code as parameter.
This deeplink is embedded in a Machine-readable-code (like QR code) and the same is rendered in the UI.
End user scans this machine-readable-code to open wallet app.
On open of wallet-app, wallet-app invokes /link-transaction endpoint.
In the UI application, once machine-readable-code is rendered, at the same time /link-status endpoint is invoked as a long polling request.

POST/linked-authorization/link-code

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

Response

Body

responseTimestring

responseobject

transactionIdstring

The same transactionId passed as part of the request.

linkCodestring

Unique random string mapped to this transactionId.

expireDateTimestring

Expire date time (ISO format) for the generated linkCode. After this date time linkCode in this request is not valid.

errorsarray of object

errorCodeenum

invalid_transaction_idlink_code_gen_failedinvalid_transactioninvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-code', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "transactionId": "text",
    "linkCode": "text",
    "expireDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Link status endpoint

The link status endpoint is invoked from IDBB UI application.

Checks the status of link code and will return the status as LINKED once the /link-transaction endpoint is called from wallet application.

POST/linked-authorization/link-status

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

This is the same transactionId sent in the /link-code request

linkCode*string

This is same linkCode returned in the generate-link-code response.

Response

Body

responseTImestring

responseobject

transactionIdstring

This is the same transactionId as sent in the request.

linkStatusenum

Link status of the linkCode passed in the request.

LINKED

linkedDateTimestring

Epoch in milliseconds at which the wallet-app acknowledged the link-code.

errorsarray of object

errorCodeenum

invalid_transaction_idinvalid_link_coderesponse_timeoutunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-status', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text",
        "linkCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTIme": "text",
  "response": {
    "transactionId": "text",
    "linkStatus": "LINKED",
    "linkedDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Link authorization code endpoint

Link authorization code endpoint is invoked from UI application.

This is a Long polling request to IDBB backend.
validates the transactionId
validates the linkCode if its LINKED.
checks the cache to see if the auth-code is generated, if yes returns the response.
If the auth-code is not yet generated, polling request waits for the configured time.
On successful response, IDBB UI should redirect to the provided redirectUri with auth-code or error details.

POST/linked-authorization/link-auth-code

Header parameters

X-XSRF-TOKEN*string

CSRF token as set in cookie key 'XSRF-TOKEN'

Body

requestTime*string

request*object

transactionId*string

This is the same transactionId sent in the /link-code request.

linkedCode*string

linkCode for which status is already received as LINKED.

Response

Body

responseTimestring

responseobject

codestring

Authorization code. Required to obtain the ID token and / or access token from the /token endpoint.

redirectUristring

Client's validated redirect URI.

statestring

The echoed state value, used to maintain state between the request and the callback

noncestring

The echoed nonce value, if one was passed with the request. Clients must validate the value before proceeding.

errorsarray

Request

const response = await fetch('/linked-authorization/link-auth-code', {
    method: 'POST',
    headers: {
      "X-XSRF-TOKEN": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "transactionId": "text",
        "linkedCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "code": "text",
    "redirectUri": "text",
    "state": "text",
    "nonce": "text"
  }
}

Linked Authentication Endpoint

Once end user provides the user identifier (UIN/VID) and all the required auth challenge to the Wallet-app, this endpoint will be invoked from wallet-app.

Supported auth-challenge depends on the integrated IDBB implementation.

Validates linkedTransactionId.
Validates null / empty individualId.

On Authentication Success: Only linkTransactionId is returned in the below response without any errors.

On Authentication Failure: Error list will be returned.

POST/linked-authorization/authenticate

Body

requestTime*string

Pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

request*object

linkedTransactionId*string

This is the same transactionId received from /link-transaction endpoint

individualId*string

User identifier (UIN/VID).

challengeList*array of AuthChallenge

Authentication Challenge.

authFactorType*enum

Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).

OTPBIOPINWLA

challenge*string

Actual challenge as string.

format*enum

Format of the challenge provided.

alpha-numericjwtencoded-jsonnumber

Response

Body

responseTimestring

responseobject

linkedTransactionIdstring

This is the same transactionId received from /link-transaction endpoint.

errorsarray of object

List of Errors in case of request validation / processing failure in IDBB server.

errorCodeenum

invalid_transaction_idinvalid_transactioninvalid_identifierinvalid_no_of_challengesauth_failedunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/authenticate', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkedTransactionId": "text",
        "individualId": "text",
        "challengeList": [
          {
            "authFactorType": "OTP",
            "challenge": "text",
            "format": "alpha-numeric"
          }
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkedTransactionId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction_id",
      "errorMessage": "text"
    }
  ]
}

Token Endpoint

The only supported client authentication method : private_key_jwt
ClientAssertion is a signed JWT with client's private key, corresponding public key should be shared with IDBB during the OIDC client creation process.
clientAssertion JWT payload must be as below:

The JWT MUST contain the following REQUIRED Claim Values and MAY contain few additional OPTIONAL Claim Values:

iss* (Issuer): This MUST contain the client_id of the OIDC / OAuth Client.

sub* (Subject): This MUST contain the client_id of the OIDC / OAuth Client.

exp* (Expiration): Time on or after which the ID token MUST NOT be accepted for processing.

iat*: Time at which the JWT was issued.

Note: The Client Assertion JWT can contain other Claims. Any Claims used that are not understood WILL be ignored.

POST/oauth/token

Body

grant_type*enum

Authorization code grant type.

authorization_code

code*string

Authorization code, sent as query param in the client's redirect URI.

client_id*string

Client Id of the OIDC client.

client_assertion_type*enum

Type of the client assertion part of this request.

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion*string

Private key signed JWT, This JWT payload structure is defined above as part of request description.

redirect_uri*string

Valid client redirect_uri. Must be same as the one sent in the authorize call.

Response

Headers

Cache-Controlenum

no-store

Pragmaenum

no-cache

Body

id_token*string

Identity token in JWT format. Will have the below claims in the payload.

access_token*string

The access token in JWT format. This token will be used to call the UserInfo endpoint. Relying party application should handle access token as opaque.

token_type*enum

The type of the access token, set to Bearer

Bearer

expires_in*number (duration)

The lifetime of the access token, in seconds.

Request

const response = await fetch('/oauth/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify({
      "grant_type": "authorization_code",
      "code": "text",
      "client_id": "text",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "text",
      "redirect_uri": "text"
    }),
});
const data = await response.json();

Response

{
  "id_token": "text",
  "access_token": "text",
  "token_type": "Bearer",
  "expires_in": 0
}

Link Transaction endpoint

The link transaction endpoint is invoked from Wallet-app.

Validates the link-code and its expiry and generates the linkTransactionId. This linkTransactionId is linked to transactionId used in the /link-code endpoint.
Returns the auth-factors, clientName, logoUrl, User claims, authorize scopes along with linkTransactionId.

Note: Wallet-app will hereafter address the transaction with this linkTransactionId for the /authenticate and /consent endpoints.

POST/linked-authorization/link-transaction

Body

requestTime*string

request*object

linkCode*string

Link code as received by the wallet-app from the QR code scanning.

Response

Body

responseTimestring

responseobject

linkTransactionIdstring

Unique link-transaction-id.

clientNamestring

Registered name of the OIDC client.

logoUrlstring

Registered OIDC client Logo URL.

authorizeScopesarray of string

List of requested scopes to be permitted by the end user.

itemsstring

essentialClaimsarray of string

List of client request mandatory claim names.

itemsstring

voluntaryClaimsarray of string

List of client request optional claim names.

itemsstring

authFactorsarray of array of AuthFactor

type*enum

Name of the authentication method

PINOTPL1-bio-deviceWallet

countinteger

Applicable for biometric based authentication, number of bio segments to be captured for authentication.

bioSubTypesarray of string

Applicable for biometric based authentication. Can be more specific about which bio segments should be captured.

itemsstring

configsobject

errorsarray of object

errorCodeenum

invalid_link_codeinvalid_transactioninvalid_client_idunknown_errorinvalid_request

errorMessagestring

Request

const response = await fetch('/linked-authorization/link-transaction', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "linkCode": "text"
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "linkTransactionId": "text",
    "clientName": "text",
    "logoUrl": "text",
    "authorizeScopes": [
      "text"
    ],
    "essentialClaims": [
      "text"
    ],
    "voluntaryClaims": [
      "text"
    ],
    "authFactors": [
      [
        {
          "type": "PIN",
          "bioSubTypes": [
            "text"
          ]
        }
      ]
    ]
  },
  "errors": [
    {
      "errorCode": "invalid_link_code",
      "errorMessage": "text"
    }
  ]
}

Wallet Binding Endpoint (Draft)

Wallet binding endpoint is invoked by Wallet's backend server.

Action will be initiated from wallet-app with authChallenge by user.
Wallet backend server will receive the authChallenge, create this request and send to IDBB to complete the binding process.
Binded walletUserId (WUID) is returned with IDBB signed certificate.

Note: Binding entry uniqueness is combination of these 3 values -> (PSUT, public-key, auth-factor-type)

POST/wallet-binding

Authorization

Header parameters

PARTNER-ID*string

An identifier for the partner.

PARTNER-API-KEY*string

An API key provided to the partner for authentication purposes.

Body

requestTime*string

request*object

individualId*string

User Id (UIN/VID).

authFactorType*string

Auth factor type to be binded for the provided key.

format*string

Format of the auth factor type supported in the wallet app.This is not stored, this value is only validated to check if its a supported format in the IDBB implementation.

challengeList*array of AuthChallenge

authFactorType*enum

Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).

OTPBIOPINWLA

challenge*string

Actual challenge as string.

format*enum

Format of the challenge provided.

alpha-numericjwtencoded-jsonnumber

publicKey*object

key to be binded in JWK format.

Response

Body

responseTime*string

responseobject

walletUserIdstring

Unique identifier given to public-key and partner specific userId mapping.

certificatestring

Key binder signed certificate.

expireDateTimestring

Expire date time of the signed certificate.

errorsarray of object

errorCodeenum

unsupported_challenge_formatkey_binding_failedinvalid_public_keyinvalid_auth_challengeduplicate_public_keyinvalid_request

errorMessagestring

Request

const response = await fetch('/wallet-binding', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "PARTNER-ID": "text",
      "PARTNER-API-KEY": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "text",
      "request": {
        "individualId": "text",
        "authFactorType": "text",
        "format": "text",
        "challengeList": [
          {
            "authFactorType": "OTP",
            "challenge": "text",
            "format": "alpha-numeric"
          }
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "walletUserId": "text",
    "certificate": "text",
    "expireDateTime": "text"
  },
  "errors": [
    {
      "errorCode": "unsupported_challenge_format",
      "errorMessage": "text"
    }
  ]
}

Configuration Endpoint

This endpoint is only for facilitating the OIDC provider details in a standard way.

Reference: https://openid.net/specs/openid-connect-discovery-1_0.html

GET/.well-known/openid-configuration

Response

Body

issuer*string

URL using the https scheme with no query or fragment component that the RP asserts as its Issuer Identifier. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.

authorization_endpoint*string

URL of the OAuth 2.0 Authorization Endpoint.

token_endpoint*string

URL of the OAuth 2.0 Token Endpoint.

userinfo_endpoint*string

URL of the OP's UserInfo Endpoint.

jwks_uri*string

URL of the OP's JSON Web Key Set [JWK] document.

registration_endpoint*string

URL of Client Registration Endpoint.

scopes_supported*array of enum

JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports.

itemsenum

openid

response_types_supported*array of enum

JSON array containing a list of the OAuth 2.0 response_type values that this OP supports.

itemsenum

code

acr_values_supportedarray of any

JSON array containing a list of the Authentication Context Class References that IDP supports.

itemsany

userinfo_signing_alg_values_supportedarray of any

JSON array containing a list of the JWS [JWS] signing algorithms.

itemsany

userinfo_encryption_alg_values_supportedarray of any

JSON array containing a list of the JWE [JWE] encryption algorithms.

itemsany

userinfo_encryption_enc_values_supportedarray of any

JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT.

itemsany

token_endpoint_auth_methods_supportedarray of enum

JSON array containing a list of Client Authentication methods supported by this Token Endpoint.

itemsenum

private_key_jwt

display_values_supportedarray of any

JSON array containing a list of the display parameter values that the OpenID Provider supports.

itemsany

claim_types_supportedarray of enum

JSON array containing a list of the Claim Types that the OpenID Provider supports.

itemsenum

normalaggregateddistributed

claims_supportedarray of string

JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for.

itemsstring

claims_locales_supportedarray of string

Languages and scripts supported for values in Claims being returned.

itemsstring

ui_locales_supportedarray of string

Languages and scripts supported for the user interface.

itemsstring

response_modes_supportedarray of enum

Mechanism to be used for returning parameters from the Authorization Endpoint.

itemsenum

query

token_endpoint_auth_signing_alg_values_supportedarray of enum

itemsenum

RS256

id_token_signing_alg_values_supportedarray of enum

itemsenum

RS256

Request

const response = await fetch('/.well-known/openid-configuration', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "issuer": "text",
  "authorization_endpoint": "text",
  "token_endpoint": "text",
  "userinfo_endpoint": "text",
  "jwks_uri": "text",
  "registration_endpoint": "text",
  "scopes_supported": [
    "openid"
  ],
  "response_types_supported": [
    "code"
  ],
  "acr_values_supported": [],
  "userinfo_signing_alg_values_supported": [],
  "userinfo_encryption_alg_values_supported": [],
  "userinfo_encryption_enc_values_supported": [],
  "token_endpoint_auth_methods_supported": [
    "private_key_jwt"
  ],
  "display_values_supported": [],
  "claim_types_supported": [
    "normal"
  ],
  "claims_supported": [
    "text"
  ],
  "claims_locales_supported": [
    "text"
  ],
  "ui_locales_supported": [
    "text"
  ],
  "response_modes_supported": [
    "query"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "RS256"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

Update OIDC Client Endpoint

API to update existing Open ID Connect (OIDC) client, it can be invoked by other modules which manages the relying parties / partners when there any updates on the fields accepted in this API.

Authentication and authorization is based on a valid JWT issued by a trusted IAM system including "update_oidc_client" scope.

PUT/client-mgmt/oidc-client/{client_id}

Authorization

Path parameters

client_id*string

Client Identifier

Example: "785b806d0e594657b05aabdb30fff8a4"

Body

requestTime*string

Current date and time when the request is sent

request*object

clientName*string

Name of the OIDC client.

Example: "ABC Health Care"

status*enum

Status of OIDC client.

activeinactive

logoUri*string (uri)

Relying party logo URI which will used to display logo in OIDC login and permissi

redirectUris*array of string (uri)

itemsstring (uri)

userClaims*array of enum

Allowed user info claims, that can be requested by OIDC client in the authorize API

itemsenum

namegiven_namefamily_namemiddle_namepreferred_usernamenicknamegenderbirthdateemailemail_verifiedphone_numberphone_number_verifiedpictureaddresslocalezoneinfo

authContextRefs*array of enum

itemsenum

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

grantTypes*array of enum

Form of Authorization Grant presented to token endpoint.

itemsenum

authorization_code

clientAuthMethods*array of enum

Auth method supported for token endpoint. At present only "private_key_jwt" is supported.

itemsenum

private_key_jwt

Response

Body

responseTimestring

Date and time when the response is generated

responseobject

clientId*string

OIDC client identifier.

errorsarray of object

List of Errors in case of request validation / processing failure in IDBB server. When request processing is fully successful, this array will be empty.

errorCodeenum

invalid_client_idinvalid_client_nameinvalid_claiminvalid_acrinvalid_uriinvalid_redirect_uriinvalid_grant_typeinvalid_client_authinvalid_request

errorMessagestring

Request

const response = await fetch('/client-mgmt/oidc-client/{client_id}', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "2022-09-22T08:03:45.000Z",
      "request": {
        "clientName": "Health Service",
        "status": "active",
        "logoUri": "http://example.com",
        "redirectUris": [
          "http://example.com/login-success"
        ],
        "userClaims": [
          "name"
        ],
        "authContextRefs": [
          "idbb:acr:generated-code"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "clientAuthMethods": [
          "private_key_jwt"
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "clientId": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_client_id",
      "errorMessage": "text"
    }
  ]
}

Create OIDC Client Endpoint

API to add new open ID connect (OIDC) clients, it can be invoked by other modules which manages the relying parties / partners.

Each relying party can associate to one or multiple OIDC client Ids.

On create, OIDC client status will be by default set to "active".

POST/client-mgmt/oidc-client

Authorization

Body

requestTime*string

Current date and time when the request is sent

request*object

clientId*string

Unique OIDC client id (Case-Sensitive). If duplicates found, request will be rejected.

Example: "785b806d0e594657b05aabdb30fff8a4"

clientName*string

Name of OIDC client.

Example: "ABC Health Care"

relyingPartyId*string

Relying Party ID of the client. This will be passed on to authentications servers when KYC is fetched.

Note: Use the client Id as relyingPartyId if there is no separate concept of relying party in the ID authentication system.

Example: "bharathi-inc"

logoUri*string (uri)

Relying party logo URI which will used to display logo in OIDC login and permission pages.

redirectUris*array of string (uri)

itemsstring (uri)

authContextRefs*array of enum

itemsenum

idbb:acr:static-codeidbb:acr:generated-codeidbb:acr:linked-walletidbb:acr:biometricsidbb:acr:biometrics-generated-codeidbb:acr:linked-wallet-static-code

publicKey*object

userClaims*array of enum

Allowed user info claims, that can be requested by OIDC client in the authorize API

itemsenum

namegiven_namefamily_namemiddle_namepreferred_usernamenicknamegenderbirthdateemailemail_verifiedphone_numberphone_number_verifiedpictureaddresslocalezoneinfo

grantTypes*array of enum

Form of Authorization Grant presented to token endpoint

itemsenum

authorization_code

clientAuthMethods*array of enum

Auth method supported for token endpoint. At present only "private_key_jwt" is supported.

itemsenum

private_key_jwt

Response

Body

responseTimestring

Date and time when the response is generated

responseobject

clientIdstring

Client id as provided in the request.

errorsarray of object

errorCodeenum

errorMessagestring

Request

const response = await fetch('/client-mgmt/oidc-client', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestTime": "2011-10-05T14:48:00.000Z",
      "request": {
        "clientId": "e-health-service",
        "clientName": "Health Service",
        "relyingPartyId": "bharath-gov",
        "logoUri": "http://example.com",
        "redirectUris": [
          "http://example.com/login-success"
        ],
        "publicKey": {},
        "authContextRefs": [
          "idbb:acr:generated-code"
        ],
        "userClaims": [
          "name"
        ],
        "grantTypes": [
          "authorization_code"
        ],
        "clientAuthMethods": [
          "private_key_jwt"
        ]
      }
    }),
});
const data = await response.json();

Response

{
  "responseTime": "text",
  "response": {
    "clientId": "text"
  },
  "errors": [
    {
      "errorCode": "duplicate_client_id",
      "errorMessage": "text"
    }
  ]
}

8 Service APIs

API standards

8.1 Identity Usage

Service Group: Client Management

8.2 Identity Management

8.3 Credential Management

8.4 Subscription Management

8.5 Administration Management

8 Service APIs

API standards

8.1 Identity Usage

Service Group: Client Management

Create OIDC Client Endpoint

Update OIDC Client Endpoint

Authorization Endpoint

Token Endpoint

UserInfo Endpoint

JSON Web Key Set Endpoint

Configuration Endpoint

Generate Link Code endpoint

Link status endpoint

Link authorization code endpoint

Link Transaction endpoint

Linked Authentication Endpoint

Linked Consent Endpoint

Wallet Binding Endpoint (Draft)

8.2 Identity Management

8.3 Credential Management

8.4 Subscription Management

8.5 Administration Management

Authorization Endpoint

UserInfo Endpoint

JSON Web Key Set Endpoint

Linked Consent Endpoint

Generate Link Code endpoint

Link status endpoint

Link authorization code endpoint

Linked Authentication Endpoint

Token Endpoint

Link Transaction endpoint

Wallet Binding Endpoint (Draft)

Configuration Endpoint

Update OIDC Client Endpoint

Create OIDC Client Endpoint