Retrieve a TrueIdentity using an access token

GET /identity/response/{access_request_code}/{identity_session_code}

Retrieve a TrueIdentity using an access token, which is granted when an identity request is approved.

This endpoint should be accessed following a successful webhook response from an identity request. Access tokens have a limited validity period.

The access token must be provided in the X-Access-Token header as a JWT.

The response contains common JWT header fields (iss, exp, etc) for ease of verification, as well as the disclosed claims.

The exp field is the expiration time of the TrueIdentity. You should not accept the response if this has elapsed.

The trueidentity.credential_jwt field is only provided if the trueidentity.credential claim was requested. This JWT contains the same fields which can be cross checked for validity.

Other credentials will be returned in the same way as the trueidentity.credential_jwt field.

Parameters

Name	In	Required	Description
`X-Correlation-Id`	header	no	Unique identifier for tracking the request through the system Example: `req-64b4a7e123456`
`Authorization`	header	yes	Access key generated from the auth API Example: `Bearer 048c2a1c-0881-4dcc-bfca-ccccccccc51`
`X-Tenant-Id`	header	yes	The tenant ID for the request Example: `048c2a1c-0881-4dcc-bfca-ccccccccc51`
`X-Request-Timestamp`	header	yes	The timestamp for the request Example: `1754261500`
`access_request_code`	path	yes	The access request code provided in the approval webhook
`identity_session_code`	path	yes	The original request code (identity_session_code)
`X-Access-Token`	header	yes	JWT access token containing the access_token and access_request_code claims, as sent to you via webhook

Responses

Status	Description
`200 OK`	Identity retrieved successfully
`400 Bad Request`	Validation error
`401 Unauthorized`	Authentication failed or invalid token
`403 Forbidden`	Unauthorized or insufficient permissions
`404 Not Found`	Validation error
`429 Too Many Requests`	Too many requests
`500 Internal Server Error`	Internal server error

Content type application/json

Response fields (200)

Field	Type	Required	Description
`data`	object	yes
`data.ref`	string	no	The reference ID for the TrueIdentity credential.
`data.iss`	string	no	The issuer of the credential (from TrueIdentity credential).
`data.sub`	string	no	The subject of the credential (from TrueIdentity credential).
`data.nbf`	integer	no	Not before time (UNIX timestamp, from TrueIdentity credential).
`data.exp`	integer	no	Expiration time (UNIX timestamp, from TrueIdentity credential).
`data.iat`	integer	no	Issued at time (UNIX timestamp, from TrueIdentity credential).
`data.jti`	string	no	Unique identifier for the credential (from TrueIdentity credential).
`data._sd`	array of string	no	Array of selective disclosure hashes for verification. See disclosures for details.
`data._sd_alg`	string	no	Hash algorithm used for selective disclosure (e.g., sha256).
`data.disclosures`	array of object	no	List of disclosed claims, each with claim name, value, salt, and verification info. To verify, recompute the hash using the same algorithm and salt provided in the disclosure, and check that the resulting hash matches the corresponding hash commitment in the _sd response. For example, if the algorithm is 'sha256' and the salt is '12345', the hash can be recomputed using the following PHP code: `hash_hmac('sha256', $value, $salt)`, replacing $value with the value of the disclosed claim and $salt with the provided salt.
`data.disclosures[].claim`	string	no	The claim string (e.g., 'trueidentity.name').
`data.disclosures[].salt`	string	no	The salt used for this disclosure (if applicable).
`data.disclosures[].value`	object	no	The value of the disclosed claim (may be string, object, or array).
`data.disclosures_missing`	array of string	no	List of requested claims that could not be disclosed (data not available). May be an empty array.
`data.trueidentity.credential_jwt`	string	no	The full SD-JWT credential, which can be independently verified and contains all claims and cryptographic proofs. Only provided if the `trueidentity.credential` claim was requested. Used to verify the contents of the `trueidentity.credential` disclosure value.
`data.request_code`	string	no	The original request code for the TrueIdentity request. Included for validation.
`data.partially_complete`	boolean	no	Whether the request was partially complete - meaning the user was not able to provide all the documents needed for the specified rule set.
`correlation_id`	string	yes
`meta`	object	no	Optional metadata about the response

Example 200 response

{
  "correlation_id": "req-64b4a7e123456",
  "data": {
    "ref": "ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
    "iss": "https://example.com/baric/credential/issuer.json",
    "sub": "https://example.com/baric/credential/trueidentity/ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
    "nbf": 1746668610,
    "exp": 1830258000,
    "iat": 1746668610,
    "jti": "https://example.com/baric/credential/trueidentity/ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
    "_sd": [
      "60529e3947b28f9103bdb7a8c7ac91a3232c6575a297615a4f3653d0af145b98",
      "24b02c545bfcc19608792436e0f421135b79a2a0590a439e7c7004b47e508fc0",
      "7d7ba7addf21fd3f94aadd02ef6ec61ebcfee40be831187d0a3295427627201d"
    ],
    "_sd_alg": "sha256",
    "disclosures": [
      {
        "claim": "trueidentity.credential",
        "value": {
          "@context": [
            "https://www.w3.org/ns/credentials/v2",
            "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json",
            "https://purl.imsglobal.org/spec/ob/v3p0/extensions.json",
            "https://bengal-bursting-plainly.ngrok-free.app/baric/credential/tv-vocab/1.jsonld"
          ],
          "credentialSubject": {
            "id": "https://example.com/baric/credential/trueidentity/ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
            "type": [
              "AchievementSubject"
            ],
            "achievement": {
              "id": "https://example.com/baric/credential/achievement/ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
              "type": [
                "Achievement"
              ],
              "criteria": {
                "narrative": "Completed the Biometrically Verified Identity Process."
              },
              "description": "TrueVault Biometrically Anchored TrueIdentity Credential",
              "name": "TrueVault TrueIdentity",
              "achievementType": "Badge",
              "image": {
                "id": "https://example.com/baric/credential/modules/TrueVault/media/images/baric-wallet-icon.png",
                "type": "Image",
                "caption": "TrueVault TrueIdentity Icon"
              },
              "inLanguage": "en-GB"
            }
          },
          "evidence": [
            {
              "id": "https://example.com/baric/credential/evidence/b16ca6c6-e00a-54a6-967f-2027bce4a3ec/c453c278-63e0-5eb1-a308-4eef057dd4fb",
              "name": "Australian Passport",
              "description": "Document number: M1****67",
              "type": [
                "Evidence"
              ],
              "dateCreated": "2025-08-29T02:49:28Z",
              "dateIssued": "2025-08-29T02:49:28Z",
              "issuer": "https://example.com/baric/credential/issuer.json",
              "tv:evidenceTypes": {
                "docType": "PASSPORT",
                "inputType": "Biometric & OCR",
                "authoritativeSource": "Australian DVS"
              },
              "tv:dataObject": {
                "truevaultReference": "c453c278-63e0-5eb1-a308-4eef057dd4fb",
                "serviceReference": "bdfecb61-f6e4-5b7f-927e-cc4cb9c9e845",
                "verifierReference": "63d59717-3a21-41ec-8427-3ab648bdb689",
                "namesVerified": "Requires 'All names verified from documents' disclosure"
              }
            }
          ],
          "id": "https://example.com/baric/credential/trueidentity/ab544aa0-e90c-555a-a987-799c0e7f2992/63cf65d5-e5dd-5c64-bad9-158a8b8b3ac0",
          "issuer": {
            "id": "https://example.com/baric/credential/issuer.json",
            "type": [
              "Profile"
            ],
            "description": "TrueVault Credential Issuer",
            "name": "TrueVault Credential Issuer",
            "url": "https://example.com/",
            "email": "issuer@truevault.com.au"
          },
          "name": "TrueIdentity",
          "type": [
            "VerifiableCredential",
            "OpenBadgeCredential"
          ],
          "validFrom": "2025-09-01T07:28:38Z",
          "validUntil": "2027-12-31T13:00:00Z",
          "issuanceDate": "2025-09-01T07:28:38Z",
          "credentialSchema": [
            {
              "id": "https://purl.imsglobal.org/spec/ob/v3p0/schema/json-ld/ob_v3p0_achievementcredential_schema.json",
              "type": "JsonSchema2020"
            }
          ],
          "credentialStatus": {
            "id": "https://example.com/baric/credential/status-lists/list/62#16067",
            "type": "BitstringStatusListEntry",
            "statusPurpose": "revocation",
            "statusListIndex": "16067",
            "statusListCredential": "https://example.com/baric/credential/status-lists/list/62"
          }
        }
      },
      {
        "claim": "trueidentity.name",
        "salt": "z4XrFD0VSY7acU74f6eiI8yV3qoI5e4Z",
        "value": "{\"first_name\": \"John\", \"last_name\": \"Smith\"}"
      },
      {
        "claim": "trueidentity.email",
        "salt": "MEPROrtvnhNshpoIEHc1C0B0K2ZYVYiK",
        "value": "john.smith@example.com"
      },
      {
        "claim": "document.driving_license.licence_number",
        "salt": "gxNp5LJsQ52cw17OCWzDavwvAQeeRx2z",
        "value": "123456789"
      }
    ],
    "disclosures_missing": [],
    "trueidentity.credential_jwt": "eyJ0eXAiOiJ2YytzZC1qd3QiLCJhbGciOiJSUzI1NiIsImp3ayI6eyJrdHkiOiJSU0EiLCJuIjoi...obfuscated...In0."
  }
}

Content type application/json

ErrorResponse (400, 404)

Field Type Required Description

error

object

yes

Every error carries a machine-readable type and a code. Match on one of these rather than on the message, which is written for people and may change.

Code	Type	HTTP
`E1001`	`VALIDATION_ERROR`	400
`E1002`	`INVALID_REQUEST`	400
`E1003`	`AUTHENTICATION_FAILED`	401
`E1004`	`UNAUTHORIZED`	403
`E1005`	`NOT_FOUND`	404
`E1006`	`CONFLICT`	409
`E1007`	`RATE_LIMIT_EXCEEDED`	429
`E1008`	`PRECONDITION_FAILED`	412
`E1009`	`CREDENTIAL_EXPIRED`	412
`E1010`	`CREDENTIAL_REVOKED`	412
`E1011`	`CREDENTIAL_PENDING_ACCEPTANCE`	412
`E1012`	`CREDENTIAL_VERIFICATION_FAILED`	412
`E2001`	`INTERNAL_ERROR`	500
`E2002`	`INTERNAL_ERROR_EMAIL`	500
`E2003`	`DATABASE_ERROR`	500
`E2004`	`EXTERNAL_SERVICE_ERROR`	502
`E2005`	`SERVICE_UNAVAILABLE`	503

error.message

string

yes

Human readable error message

error.type

string

yes

Error type identifier

One of: VALIDATION_ERROR, INVALID_REQUEST, AUTHENTICATION_FAILED, UNAUTHORIZED, NOT_FOUND, CONFLICT, RATE_LIMIT_EXCEEDED, PRECONDITION_FAILED, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CREDENTIAL_PENDING_ACCEPTANCE, CREDENTIAL_VERIFICATION_FAILED, INTERNAL_ERROR, INTERNAL_ERROR_EMAIL, DATABASE_ERROR, EXTERNAL_SERVICE_ERROR, SERVICE_UNAVAILABLE

error.code

string

yes

Machine-readable error code

One of: E1001, E1002, E1003, E1004, E1005, E1006, E1007, E1008, E1009, E1010, E1011, E1012, E2001, E2002, E2003, E2004, E2005

error.timestamp string yes

error.correlation_id string yes

error.details

object

Additional error context

Example 400 response

{
  "error": {
    "message": "string",
    "type": "VALIDATION_ERROR",
    "code": "E1001",
    "timestamp": "2026-02-20T03:14:15Z",
    "correlation_id": "string"
  }
}

Content type application/json

Response fields (401)

Field	Type	Required	Description
`error`	object	yes

Example 401 response

{
  "error": {
    "type": "AUTHENTICATION_FAILED",
    "code": "E1003"
  }
}

Content type application/json

Response fields (403)

Field	Type	Required	Description
`error`	object	yes

Example 403 response

{
  "error": {
    "type": "UNAUTHORIZED",
    "code": "E1004"
  }
}

Content type application/json

Response fields (429)

Field	Type	Required	Description
`error`	object	yes

Example 429 response

{
  "error": {
    "type": "RATE_LIMIT_EXCEEDED",
    "code": "E1007"
  }
}

Content type application/json

Response fields (500)

Field	Type	Required	Description
`error`	object	yes

Example 500 response

{
  "error": {
    "type": "INTERNAL_ERROR",
    "code": "E2001"
  }
}

Example request

curl --request GET \
  --url https://api.sandbox.truevault.com.au/api/v1/identity/response/{access_request_code}/{identity_session_code} \
  --header 'X-Correlation-Id: <value>' \
  --header 'Authorization: <value>' \
  --header 'X-Tenant-Id: <value>' \
  --header 'X-Request-Timestamp: <value>' \
  --header 'X-Access-Token: <value>'