LogoLogo
Give FeedbackGovStack Home
Development
Development
  • Identity
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF

8 Service APIs

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

Last updated 11 months ago

Was this helpful?

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 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 .

API standards

  • The microservice interfaces are defined as per .

  • For implementation purposes, it is suggested to refer .

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

Service Group: Client Management

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

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.

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 .

The provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.

Identity-Provider YAML
GovStack non-functional requirements document
GovStack non-functional requirements document
this GitHub repository
OPENAPI Ver3.0 standards
TMF630_REST_API_Design_Guidelines
Secure Biometrics Interface standards

Authorization Endpoint

get

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.

Query parameters
scopestring · enumRequired

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.

Default: openid profilePossible values:
response_typestring · enumRequired

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

Possible values:
client_idstring · max: 256Required

Valid OAuth 2.0 Client Identifier in the Authorization Server.

redirect_uristring · uriRequired

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 · max: 256Optional

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.

noncestringOptional

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.

displaystring · enumOptional

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

Possible values:
promptstring · enumOptional

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: consentPossible values:
max_agenumberOptional

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_localesstringOptional

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_valuesstring · enumOptional

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.

Possible values:
claims_localesstringOptional

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.

claimsstringOptional

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.

Responses
200
OK Loads IDBB UI application in browser for interacting with user for Login process
get
GET /authorize?scope=openid+profile&response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com HTTP/1.1
Host: 
Accept: */*
200

OK

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

No content

UserInfo Endpoint

get

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

Authorizations
Responses
200
OK
application/jwt
Responsestring · 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.

401
Unauthorized
get
GET /oidc/userinfo HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
text

JSON Web Key Set Endpoint

get

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

Responses
200
OK
application/json
get
GET /.well-known/jwks.json HTTP/1.1
Host: 
Accept: */*
200

OK

{
  "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

get

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

Responses
200
OK
application/json
get
GET /.well-known/openid-configuration HTTP/1.1
Host: 
Accept: */*
200

OK

{
  "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"
  ]
}

Create OIDC Client Endpoint

post

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".

Authorizations
Body

OIDC client details

requestTimestringRequired

Current date and time when the request is sent

Responses
200
OK
application/json
401
Unauthorized
post
POST /client-mgmt/oidc-client HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 387

{
  "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"
    ]
  }
}
{
  "responseTime": "text",
  "response": {
    "clientId": "text"
  },
  "errors": [
    {
      "errorCode": "duplicate_client_id",
      "errorMessage": "text"
    }
  ]
}

Update OIDC Client Endpoint

put

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.

Authorizations
Path parameters
client_idstringRequired

Client Identifier

Example: 785b806d0e594657b05aabdb30fff8a4
Body
requestTimestringRequired

Current date and time when the request is sent

Responses
200
OK
application/json
put
PUT /client-mgmt/oidc-client/{client_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 329

{
  "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"
    ]
  }
}
200

OK

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

Token Endpoint

post

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.

  1. The only supported client authentication method : private_key_jwt
  2. ClientAssertion is a signed JWT with client's private key, corresponding public key should be shared with IDBB during the OIDC client creation process.
  3. 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.

Body
grant_typestring · enumRequired

Authorization code grant type.

Possible values:
codestringRequired

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

client_idstringRequired

Client Id of the OIDC client.

client_assertion_typestring · enumRequired

Type of the client assertion part of this request.

Possible values:
client_assertionstringRequired

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

redirect_uristringRequired

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

Responses
200
OK
application/json
400
Bad Request
application/json
post
POST /oauth/token HTTP/1.1
Host: 
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 197

"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'"
{
  "id_token": "text",
  "access_token": "text",
  "token_type": "Bearer",
  "expires_in": 1
}

Generate Link Code endpoint

post

Generate link code request is raised from IDBB UI application.

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

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

Body
requestTimestringRequired
Responses
200
OK
application/json
post
POST /linked-authorization/link-code HTTP/1.1
Host: 
X-XSRF-TOKEN: text
Content-Type: application/json
Accept: */*
Content-Length: 57

{
  "requestTime": "text",
  "request": {
    "transactionId": "text"
  }
}
200

OK

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

Link status endpoint

post

The link status endpoint is invoked from IDBB UI application.

  1. Checks the status of link code and will return the status as LINKED once the /link-transaction endpoint is called from wallet application.
Header parameters
X-XSRF-TOKENstringRequired

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

Body
requestTimestringRequired
Responses
200
OK
application/json
post
POST /linked-authorization/link-status HTTP/1.1
Host: 
X-XSRF-TOKEN: text
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "requestTime": "text",
  "request": {
    "transactionId": "text",
    "linkCode": "text"
  }
}
200

OK

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

Link authorization code endpoint

post

Link authorization code endpoint is invoked from UI application.

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

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

Body
requestTimestringRequired
Responses
200
OK
application/json
post
POST /linked-authorization/link-auth-code HTTP/1.1
Host: 
X-XSRF-TOKEN: text
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "requestTime": "text",
  "request": {
    "transactionId": "text",
    "linkedCode": "text"
  }
}
200

OK

{
  "responseTime": "text",
  "response": {
    "code": "text",
    "redirectUri": "text",
    "state": "text",
    "nonce": "text"
  },
  "errors": [
    {
      "errorCode": "invalid_transaction",
      "errorMessage": "text"
    }
  ]
}

Link Transaction endpoint

post

The link transaction endpoint is invoked from Wallet-app.

  1. Validates the link-code and its expiry and generates the linkTransactionId. This linkTransactionId is linked to transactionId used in the /link-code endpoint.

  2. 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.

Body
requestTimestringRequired
Responses
200
OK
application/json
post
POST /linked-authorization/link-transaction HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "requestTime": "text",
  "request": {
    "linkCode": "text"
  }
}
200

OK

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

Linked Authentication Endpoint

post

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.

  1. Validates linkedTransactionId.
  2. 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.

Body
requestTimestringRequiredPattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
Responses
200
OK
application/json
post
POST /linked-authorization/authenticate HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 172

{
  "requestTime": "text",
  "request": {
    "linkedTransactionId": "text",
    "individualId": "text",
    "challengeList": [
      {
        "authFactorType": "OTP",
        "challenge": "text",
        "format": "alpha-numeric"
      }
    ]
  }
}
200

OK

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

Linked Consent Endpoint

post

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.

  1. Validates linkedTransactionId.
  2. Validate accepted claims and permitted scopes in the request.
  3. If valid, stores the accepted claims and permitted scopes in the datastore.
Body
requestTimestringRequiredPattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
Responses
200
OK
application/json
post
POST /linked-authorization/consent HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "requestTime": "text",
  "request": {
    "linkedTransactionId": "text",
    "permittedAuthorizeScopes": [
      "text"
    ],
    "acceptedClaims": [
      "text"
    ]
  }
}
200

OK

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

Wallet Binding Endpoint (Draft)

post

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

  1. Action will be initiated from wallet-app with authChallenge by user.
  2. Wallet backend server will receive the authChallenge, create this request and send to IDBB to complete the binding process.
  3. 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)

Authorizations
Header parameters
PARTNER-IDstringRequired

An identifier for the partner.

PARTNER-API-KEYstringRequired

An API key provided to the partner for authentication purposes.

Body
requestTimestringRequired
Responses
200
OK
application/json
post
POST /wallet-binding HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
PARTNER-ID: text
PARTNER-API-KEY: text
Content-Type: application/json
Accept: */*
Content-Length: 198

{
  "requestTime": "text",
  "request": {
    "individualId": "text",
    "authFactorType": "text",
    "format": "text",
    "challengeList": [
      {
        "authFactorType": "OTP",
        "challenge": "text",
        "format": "alpha-numeric"
      }
    ],
    "publicKey": {}
  }
}
200

OK

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

Get the status by eventID

Authorizations
Path parameters
eventIdintegerRequired

Event ID to get the status

Query parameters
languagestringRequired

Language Code in 3 letters. Example- eng

Responses
200
OK
application/json
401
Unauthorized
application/json
get
GET /events/{eventId}?language=LANGCODE?language=text HTTP/1.1
Host: 
Authorization: string YOUR_SECRET_TOKEN
Accept: */*
{
  "id": "text",
  "version": "text",
  "response": {
    "eventId": "text",
    "eventType": "text",
    "eventStatus": "text",
    "individualId": "text",
    "summary": "text",
    "timestamp": "text",
    "info": {
      "purpose": "text",
      "applicantName": "text",
      "partnerId": "text",
      "partnerLogo": "text",
      "partnerName": "text",
      "paymentStatus": "text",
      "partnerTransactionId": "text",
      "deliveryAddress": "text",
      "authenticationMode": "text",
      "vidType": "text",
      "vid": "text",
      "attributeList": "text",
      "downloadCardLink": "text",
      "orderTrackingLink": "text",
      "trackingId": "text"
    }
  },
  "requestTime": "text"
}
get

Get the status by eventID

Authorizations
Path parameters
langCodestringRequired

Language Code in 3 letters. Example- eng

Query parameters
fromDatestringRequired

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

pageFetchstringOptional

integer greater than 0, default is 10

pageStartstringOptional

integer starting from 0, default is 0

searchTextstringOptional

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

serviceTypestringOptional

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

sortTypestringOptional

ASC/DESC, default is ASC

Default: ASC
statusFilterstringOptional

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

toDatestringOptional

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

Header parameters
localestringRequired

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

time-zone-offsetstringRequired

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

Responses
200
OK
application/json
401
Unauthorized
application/json
get
GET /service-history/{langCode}?fromDate=text HTTP/1.1
Host: 
Authorization: string YOUR_SECRET_TOKEN
locale: text
time-zone-offset: text
Accept: */*
{
  "id": "text",
  "version": "text",
  "errors": [
    {
      "errorCode": "text",
      "errorMessage": "text"
    }
  ],
  "response": {
    "pageNo": 1,
    "pageSize": 1,
    "totalItems": 1,
    "totalPages": 1,
    "data": []
  },
  "responseTime": "text"
}
post

Format for sharing identity credentials with an identity partner

Body
idstringOptional

id to hit API

Default: mosip.resident.share.credential
requesttimestringOptional

2021-10-19T17:01:59.538Z

versionstringOptional

Example: 1.0

Responses
200
EventId generated successfully.
application/json
401
Unauthorized
application/json
post
POST /share-credential HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "id": "text",
  "request": {
    "partnerId": "text",
    "sharableAttributes": [],
    "purpose": "text",
    "consent": "text"
  },
  "requesttime": "text",
  "version": "text"
}
{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "metadata": {},
  "response": {
    "status": "text"
  },
  "errors": {}
}
post

Download the personalized UIN Card

Authorizations
Body
idstringOptional

id for downloading card

versionstringOptional

version of API

requesttimestringOptional

timestamp when we hit API

Responses
200
OK - The PDF Bytes
400
Bad Request
application/json
401
Unauthorized
application/json
post
POST /download/personalized-card HTTP/1.1
Host: 
Authorization: string YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "id": "text",
  "version": "text",
  "requesttime": "text",
  "request": {
    "html": "text"
  }
}

No content

post

Update UIN request raised by the resident/citizen

Authorizations
Body
idstringOptional

id to hit update uin API.

versionstringOptional

version of API

requestTimestringOptional

timestamp when we get resposne.

Responses
200
OK, update is successful.
application/json
post
POST /update-uin HTTP/1.1
Host: 
Authorization: string YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 214

{
  "id": "text",
  "version": "text",
  "requestTime": "text",
  "request": {
    "transactionID": "text",
    "individualId": "text",
    "individualIdType": "text",
    "otp": "text",
    "identityJson": "text",
    "documents": [
      {
        "name": "text",
        "value": "text"
      }
    ]
  }
}
200

OK, update is successful.

{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "response": {},
  "errors": [
    {
      "errorCode": "text",
      "message": "text"
    }
  ]
}
patch

Activate/Deactivate UIN

Body
idstringOptional

Example - govstack.updateIdentity

versionstringOptional

v1

requesttimestringOptional

timestamp when API executes

metaDataobjectOptional
Responses
200
UIN activation status successfully updated
application/json
204
No content
401
Unauthorized
403
Forbidden
patch
PATCH /updateIdentity HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "id": "text",
  "version": "text",
  "requesttime": "text",
  "metaData": {},
  "request": {
    "status": "text",
    "identity": {},
    "documents": [],
    "verifiedAttributes": [],
    "registrationId": "text",
    "uin": "text"
  }
}
{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "metaData": {},
  "response": {
    "status": "text",
    "identity": {},
    "documents": [],
    "verifiedAttributes": [
      {
        "attributeString": "text"
      }
    ]
  },
  "errors": [
    {
      "errorCode": "text",
      "errorMessage": "text"
    }
  ]
}
post

Command to be used by administrators to unblock UIN

Body
idstringOptional

id to hit API

versionstringOptional

version of API

requesttimestringOptional

timestamp when API executed

metadataobjectOptional
Responses
200
UIN unblocked successfully.
application/json
post
POST /unblock HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "id": "text",
  "version": "text",
  "requesttime": "text",
  "metadata": {},
  "request": {
    "id": "text",
    "idType": "text",
    "status": "text",
    "expiryTimestamp": "text"
  }
}
200

UIN unblocked successfully.

{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "metadata": {},
  "response": {
    "id": "text",
    "idType": "text",
    "status": "text",
    "expiryTimestamp": "text"
  },
  "errors": [
    {
      "errorCode": "text",
      "message": "text"
    }
  ]
}
post

Command to be used by administrators to block UIN

Body
idstringOptional

id to hit API

versionstringOptional

version of API

requesttimestringOptional

timestamp when API executed

metadataobjectOptional
Responses
200
UIN blocked successfully.
application/json
post
POST /block HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "id": "text",
  "version": "text",
  "requesttime": "text",
  "metadata": {},
  "request": {
    "id": "text",
    "idType": "text",
    "status": "text",
    "expiryTimestamp": "text"
  }
}
200

UIN blocked successfully.

{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "metadata": {},
  "response": {
    "id": "text",
    "idType": "text",
    "status": "text",
    "expiryTimestamp": "text"
  },
  "errors": [
    {
      "errorCode": "text",
      "message": "text"
    }
  ]
}
  • API standards
  • 8.1 Identity Usage
  • POSTCreate OIDC Client Endpoint
  • PUTUpdate OIDC Client Endpoint
  • GETAuthorization Endpoint
  • POSTToken Endpoint
  • GETUserInfo Endpoint
  • GETJSON Web Key Set Endpoint
  • GETConfiguration Endpoint
  • POSTGenerate Link Code endpoint
  • POSTLink status endpoint
  • POSTLink authorization code endpoint
  • POSTLink Transaction endpoint
  • POSTLinked Authentication Endpoint
  • POSTLinked Consent Endpoint
  • POSTWallet Binding Endpoint (Draft)
  • 8.2 Identity Management
  • PUT/enrollment
  • 8.3 Credential Management
  • POST/share-credential
  • GET/events/{eventId}?language=LANGCODE
  • POST/download/personalized-card
  • POST/update-uin
  • GET/service-history/{langCode}
  • PATCH/updateIdentity
  • POST/unblock
  • POST/block
  • 8.4 Subscription Management
  • 8.5 Administration Management
put

Create user enrollment

Body
idstringOptionalExample: govstack.enrollment
versionstringOptionalExample: v1
requesttimestringOptionalExample: 2022-06-06T13:24:50.605Z
Responses
200
Successfully enrolled
application/json
201
New user enrolled successfully.
401
Unauthorized
403
Not Found
404
Not Found
put
PUT /enrollment HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1121

{
  "id": "govstack.enrollment",
  "version": "v1",
  "requesttime": "2022-06-06T13:24:50.605Z",
  "request": {
    "offlineMode": false,
    "id": "text",
    "refId": "text",
    "fields": {
      "gender": "[ { \"language\" : \"eng\", \"value\" : \"Male\" } ]",
      "city": "[ { \"language\" : \"eng\", \"value\" : \"Kenitra\" } ]",
      "postalCode": 14022,
      "fullName": "[ { \"language\" : \"eng\", \"value\" : \"Enrollment89 I290\" } ]"
    },
    "metaInfo": {
      "metaData": "[ { label\" : \"centerId\", \"value\" : \"10001\" }, { \"label\" : \"machineId\", \"value\" : \"10002\" } ]",
      "capturedRegisteredDevices": "[]",
      "operationsData": "[ { \"label\": \"officerId\", \"value\": \"globaladmin\" }, { \"label\" : \"officerBiometricFileName\",\"value\":null } ]"
    },
    "process": "NEW",
    "source": "REGISTRATION_CLIENT",
    "audits": [
      {
        "eventId": "RPR_405",
        "hostName": "Techno-367",
        "idType": "REGISTRATION_ID",
        "hostIp": "192.168.1.100"
      }
    ],
    "biometrics": {
      "version": {
        "major": 1,
        "minor": 1
      },
      "cbeffversion": {
        "major": 1,
        "minor": 1
      },
      "birInfo": {
        "creator": "text",
        "index": "text",
        "payload": [
          "payload"
        ],
        "integrity": true,
        "creationDate": "text",
        "notValidBefore": "text",
        "notValidAfter": "text"
      },
      "segment": [],
      "others": {}
    },
    "documents": {}
  }
}
{
  "id": "text",
  "version": "text",
  "responsetime": "text",
  "metaData": {
    "data": "text"
  },
  "response": [],
  "errors": []
}