# 8 Service APIs
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](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) 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](https://github.com/GovStackWorkingGroup/bb-identity/tree/main/test/openAPI).
## API standards
* The microservice interfaces are defined as per [OPENAPI Ver3.0 standards](https://swagger.io/specification/).
* For implementation purposes, it is suggested to refer [TMF630\_REST\_API\_Design\_Guidelines](https://www.tmforum.org/resources/standard/tmf630-rest-api-design-guidelines-4-2-0/).
## 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 from 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](https://standards.ieee.org/ieee/3167/10925/)
#### Service Group: Client Management
{% openapi src="" path="/client-mgmt/oidc-client" method="post" %}
{% endopenapi %}
{% openapi src="" path="/client-mgmt/oidc-client/{client\_id}" method="put" %}
{% endopenapi %}
{% openapi src="" path="/authorize" method="get" %}
{% endopenapi %}
{% openapi src="" path="/oauth/token" method="post" %}
{% endopenapi %}
{% openapi src="" path="/oidc/userinfo" method="get" %}
{% endopenapi %}
{% openapi src="" path="/.well-known/jwks.json" method="get" %}
{% endopenapi %}
{% openapi src="" path="/.well-known/openid-configuration" method="get" %}
{% endopenapi %}
For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.
{% openapi src="" path="/linked-authorization/link-code" method="post" %}
{% endopenapi %}
{% openapi src="" path="/linked-authorization/link-status" method="post" %}
{% endopenapi %}
{% openapi src="" path="/linked-authorization/link-auth-code" method="post" %}
{% endopenapi %}
{% openapi src="" path="/linked-authorization/link-transaction" method="post" %}
{% endopenapi %}
{% openapi src="" path="/linked-authorization/authenticate" method="post" %}
{% endopenapi %}
{% openapi src="" path="/linked-authorization/consent" method="post" %}
{% endopenapi %}
{% openapi src="" path="/wallet-binding" method="post" %}
{% endopenapi %}
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](https://github.com/GovStackWorkingGroup/bb-identity/blob/1.0-QA/api/Identity-Provider.yaml).
The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) 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).
This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.
## **8.3 Credential 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.4 Subscription 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.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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://identity.govstack.global/identity-1.0/8-apis-and-services.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.