Created by User a96df, last modified on Nov 29, 2022

This document includes endpoints used by the iam-manager microservice, as well as some commonly used endpoints for development purposes.

Postman collection of the VIDA API:

Notes about the collection:

  • Obtaining the Bearer token requires client_id and client_secret which can be found in HashiCorp Vault (brave and stage)

  • Current requests are not adding any Authorization . To do so, first obtain the token then set Authorization: Bearer $token

  • Changing the environment should be as simple as changing Postman collection’s Variables

Environments overview

SaFi environment

Current VIDA environment

Expected VIDA environment

Authorization

Lifecycle

brave

test

dev (question)

Obtained via VIDA’s dev keycloak - https://keycloak.auth-dev.vida.id/auth/realms/push-signing/protocol/openid-connect/token

Ongoing

stage

test

stage

Obtained via VIDA’s stage keycloak - https://keycloak.auth-stage.vida.id/auth/realms/push-signing/protocol/openid-connect/token

Ongoing

production

/

production (question)

TBD

Ongoing

epfs

test

/

None required

Environment scheduled to be removed and all credentials scheduled to be migrated to VIDA dev once EPFS testing is completed

Action items for the future:

  • Once EPFS testing is complete and the SaFi epfs environment is no longer required, VIDA should be notified to execute the removal of and migration from their test environment

Endpoints overview

Depending on the selected environment, base URL is different:

Current API version is v1 , which gives us api/v1 as the API version value.

Following is the list of paths, included in the VIDA BE folder (updated 24th Oct '22) and in the attached Postman collection:

Endpoint

Notes

Request body

(OK) Response

POST /device/register

Obtains an unbound credentialId which is in turn used by VIDA’s SDK to create new signing credentials and attach them to the aforementioned credentialId in VIDA’s system.

credentialId expires after 60 seconds and should be registered via the VIDA SDK in that time frame.

{
    "presence": "SILENT_AND_ENFORCE_USER_PRESENCE"
}

All options for presence include:

  • SILENT_USER - used if the credentials should have a key only for silent signing

  • ENFORCE_USER_PRESENCE - used if the credentials should have a key only for presence signing

  • SILENT_AND_ENFORCE_USER_PRESENCE - used if the credentials should have keys both for silent and presence signing, this is our usecase

{
    "credential_id": "2a64ab4e-c9de-4f2c-a9ef-2b16373dcf6d"
}

POST /device/fetch-public-key

Gets public keys (in case of SILENT_AND_ENFORCE_USER_PRESENCE credentials) for both keypairs.

{
    "credential_id": "2a64ab4e-c9de-4f2c-a9ef-2b16373dcf6d"
}
{
"silent_key":"Ng7mjCcU+qaTZ0ac9g52dNkY80NDbunm/qcD07PR7TQgmbS7FDV0dl2kzz9kr7v386yLRf0txu+Kyc+teE1Uxw==",
"presence_key":"vLQeHY7sFTwUKEh88gVSLmGsCIF+xggnW5cPVbLX9S9TcvlyJTgyddgSfN2R0igwlWaWO7DSKBXnMyL78rdDjA=="
}

POST /device/unregister-device

Removes signing credentials from the VIDA system.

{
    "credential_id": "2a64ab4e-c9de-4f2c-a9ef-2b16373dcf6d"
}
{
  "status": "SUCCESS",
  "reason": "Credential id is inactive"
}

POST /device/status

Gets status of signing credentials in the VIDA system.

This requests is NOT used by our application, but is useful for development purposes.

{
    "credential_id": "2a64ab4e-c9de-4f2c-a9ef-2b16373dcf6d"
}
{
  "status": "SUCCESS",
  "reason": "Public key signatures added"
}

Unexpected behavior and error responses can be found in the documentation provided by VIDA, which can be found in the VIDA BE folder (updated 24th Oct '22).

Attachments:

VIDA API.postman_collection.json (application/json)