Skip to main content

Access Tracking

Every time a share token is used to verify an applicant's data, TrustGate logs the access. Use the access history endpoint to monitor who accessed shared data, when, and whether the access succeeded.

View Access History​

Get the access log for all share tokens belonging to an applicant.

curl -X GET "https://api.bytrustgate.com/api/v1/kyc-share/history/550e8400-e29b-41d4-a716-446655440000?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Maximum number of access log entries to return

Response (200 OK)​

{
  "logs": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "token_prefix": "aB3dEfGh",
      "shared_with": "Partner Company Inc",
      "requester_ip": "203.0.113.42",
      "requester_domain": "partner-company.com",
      "accessed_at": "2026-02-04T15:00:00Z",
      "success": true,
      "failure_reason": null,
      "accessed_permissions": ["basic_info", "id_verification", "screening"]
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "token_prefix": "xY9zAbCd",
      "shared_with": "Another Service Ltd",
      "requester_ip": "198.51.100.17",
      "requester_domain": null,
      "accessed_at": "2026-02-03T10:30:00Z",
      "success": false,
      "failure_reason": "Token expired",
      "accessed_permissions": []
    }
  ],
  "total": 2
}

Response Fields​

FieldTypeDescription
idUUIDUnique access log entry ID
token_prefixstringFirst 8 characters of the token (for identification)
shared_withstringName of the entity the token was shared with
requester_ipstring or nullIP address of the requester
requester_domainstring or nullDomain of the requester (if detectable)
accessed_atdatetimeWhen the access occurred
successbooleanWhether the verification succeeded
failure_reasonstring or nullWhy it failed (e.g., "Token expired", "Token revoked", "Uses exhausted")
accessed_permissionsarrayWhich permission categories were accessed

What Gets Logged​

Every call to POST /api/v1/kyc-share/verify is logged, whether it succeeds or fails:

Successful Access​

  • Requester IP address
  • Requester domain (from headers)
  • Requester user agent
  • Timestamp
  • Which permissions were accessed
  • success: true

Failed Access​

  • Same metadata as successful access
  • success: false
  • failure_reason with one of:
    • "Token expired" — Token past its expires_at
    • "Token revoked" — Token was manually revoked
    • "Uses exhausted" — Token reached max_uses
    • "Token invalid" — Token not found

Using Access Logs​

Audit Compliance​

Access logs provide the audit trail needed for compliance reviews:

# Get all access history for a specific applicant
curl -X GET "https://api.bytrustgate.com/api/v1/kyc-share/history/550e8400-e29b-41d4-a716-446655440000?limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Each log entry includes the token_prefix which can be cross-referenced with the token list to see who the token was shared with and what permissions it granted.

Cross-Reference with Tokens​

To get a complete picture of sharing activity for an applicant:

  1. List tokens to see all tokens created:

    curl -X GET "https://api.bytrustgate.com/api/v1/kyc-share/tokens/550e8400-e29b-41d4-a716-446655440000?include_expired=true" \
      -H "Authorization: Bearer YOUR_API_KEY"

  2. View access history to see all verification attempts:

    curl -X GET "https://api.bytrustgate.com/api/v1/kyc-share/history/550e8400-e29b-41d4-a716-446655440000" \
      -H "Authorization: Bearer YOUR_API_KEY"

  3. Match token_prefix values between the two responses to see which tokens were used and by whom.

Detect Suspicious Activity​

Monitor access logs for patterns that may indicate misuse:

  • Multiple failed attempts from the same IP
  • Access from unexpected domains
  • Tokens being used more frequently than expected

Next Steps​