> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/authentication/authentication-factors/biometric-device-selfie-id/integration-methods/selfie-id-api/api/integration-flow.md). # Integration Flow The workflow for integrating with the VIDA Authentication system can be divided into three main parts: Transaction Initiation, Transaction Completion, and Transaction Management. These parts encompass several steps, which are described below: ### Transaction Initiation * The process starts when a user action triggers the partner server to contact the VIDA Authentication Server to initiate an authentication or provisioning transaction. * The partner server sends a request to the VIDA Authentication Server, which includes authentication or provisioning parameters. * To authenticate the request, a shared secret (such as an API key) is used. * The VIDA Authentication Server responds to the partner server with a session ID, a user challenge, and a bearer token. * The bearer token is intended for the user agent or client (such as a mobile app or browser) to complete the transaction. ### Transaction Completion * This step involves the user responding to the transaction challenge. * The user interacts with the end-user client device or browser to complete the transaction. * For example, the user may be prompted to provide a selfie for face match or enter an OTP (One-Time Password) for OTP-based authentication. * The user includes the bearer token received in the previous step to authenticate their actions. ### Transaction Management: * These management APIs allow the partner server to interact with the VIDA Authentication Server for transaction-related operations. * The partner server can use these APIs to query the status of a transaction or terminate (kill) a transaction if needed. * Similar to the transaction initiation step, the partner server authenticates its requests to the VIDA Authentication Server using a shared secret (e.g., API key). It's worth noting that both provisioning and authentication workflows follow similar steps, with variations in parameters depending on the specific use case. ## Provisioning Workflow The mobile client initiates a request to the partner server for provisioning a credential. The workflow for provisioning with the VIDA Authentication system proceeds as follows: 1. The partner server receives the provisioning request from the mobile client. 2. The partner server contacts the VIDA Authentication server to initiate the provisioning process, using the client secret for authentication. 3. The VIDA Authentication server responds to the partner server with the following information: * A bearer token that the mobile client will use to authenticate against the VIDA Authentication server. * A session ID to identify and track the provisioning session. * A challenge that the mobile client needs to respond to in order to confirm the completion of the provisioning process. * In the case of **Face Authentication challenge**, the user sends a selfie as the response. * In the case of **OTP challenge**: * The VIDA Authentication server sends a key to the partner server, which will be presented to the mobile app. * The user can enter the key in an authenticator app (e.g., Google Authenticator) to generate an OTP. * The generated OTP will be used as a response from the mobile client during the provisioning workflow. 4. The partner server relays the information received from the VIDA Authentication server to the mobile client for further processing and user action. 5. The mobile client completes the challenge and responds to the VIDA API with the bearer token acquired in step 3 and the response to the challenge. 6. The VIDA API validates the response received from the mobile client. 7. Upon successful validation, the VIDA API responds back to the mobile client with a signed assertion that includes the Credential ID as the subject. 8. The partner mobile app submits the signed assertion to the partner server, confirming the completion of the provisioning process. 9. The partner server can query the VIDA Authentication server for the status of the provisioning request using the session ID acquired in step 3. 10. If needed, the partner server can send an abort request to the VIDA Authentication server for the specific session ID, indicating that no further action should be honored from the partner client for that session. By following this workflow, the mobile client can successfully initiate the provisioning process with the VIDA Authentication system through the partner server. The authentication challenges are completed, and the status and control of the provisioning process can be managed by the partner server using the provided session ID. ## Authentication Workflow ### Server-Driven Authentication: FaceMatch
### Transaction Initiation Request The partner server commences the authentication process by sending a request to the VIDA Authentication server using Transaction init API . This request includes authentication parameter like auth type which in this context is `FaceMatch` and the `template_url` along with the `client_id` and `client_secret` . **Processing Authentication Request** The VIDA Authentication server meticulously verifies the partner server's request using the provided client secret. Upon successful validation, the VIDA Authentication server provides the following details to the partner server: * A `uri`, indicating where the subsequent request should be initiated for the authentication challenge. * A `bearer_token` for secure server-to-server authentication. * A `session_identifier`, serving as a unique identifier to monitor the ongoing authentication session. ### **Transaction Completion Request** The authentication request will be initiated by the partner server to the Follow up `uri` and the `bearer_token` received part of the Initiation request, along with the `client_id` and `image` for the face match. **Validating Authentication Response** Post verification, the VIDA Authentication server responds with a signed access token. This access token in JWT format, will include crucial details such as session identified, liveness and face match scores. ### **Querying Authentication Status** If necessary, the partner server possesses the flexibility to check the current authentication status from the VIDA Authentication server, utilizing the previously obtained `session_identifier`. ### Abort Request The partner server can stop the process by sending an kill request with the `session_identifier`, if necessary. ### Authentication from Mobile Client The mobile client initiates a request to the partner server for authentication using a credential. 1. The mobile client sends a request to the partner server for authentication. 2. The partner server contacts the VIDA Authentication server to initiate the authentication process, using the client secret for authentication. 3. The VIDA Authentication server responds to the partner server with the following information: * A bearer token that the mobile client will use to authenticate against the VIDA Authentication server. * A session ID to identify and track the authentication session. * A challenge that the mobile client needs to respond to in order to confirm the completion of the authentication process. * In the case of **Face Authentication** challenge, the user sends a selfie as the response. * In the case of **OTP challenge**, the user provides the OTP obtained from an authenticator application. 4. The partner server relays the information received from the VIDA Authentication server to the mobile client for further processing and user action. 5. The mobile client completes the challenge and responds to the VIDA API with the bearer token acquired in step 3 and the response to the challenge. 6. The VIDA API validates the response received from the mobile client. 7. Upon successful validation, the VIDA API responds back to the mobile client with a signed assertion that includes the Credential ID as the subject. 8. The partner mobile app submits the signed assertion to the partner server, confirming the completion of the authentication process. 9. The partner server can query the VIDA Authentication server for the status of the authentication request using the session ID acquired in step 3. 10. If needed, the partner server can send an abort request to the VIDA Authentication server for the specific session ID, indicating that no further action should be honored from the partner client for that session.