Skip to main content

Generating Tokens

Reusable KYC tokens are secure credentials that allow users to share their verified identity with other services.

Token Types​

User-Controlled Tokens​

Tokens generated by verified users to share at their discretion:

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "token_type": "user_controlled",
    "data_scope": ["full_name", "date_of_birth", "verification_status"],
    "expires_in_hours": 24,
    "max_uses": 1
  }'

Response​

{
  "token_id": "token_abc123",
  "token": "gcvt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "user_controlled",
  "data_scope": ["full_name", "date_of_birth", "verification_status"],
  "expires_at": "2025-01-21T14:30:00Z",
  "max_uses": 1,
  "uses_remaining": 1,
  "created_at": "2025-01-20T14:30:00Z"
}

Organization Request Tokens​

Tokens requested by receiving organizations:

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/request \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_identifier": "john.doe@example.com",
    "identifier_type": "email",
    "data_requested": ["full_name", "date_of_birth", "screening_status"],
    "purpose": "account_opening",
    "callback_url": "https://your-app.com/kyc-callback"
  }'

Pre-Authorized Tokens​

For trusted partner relationships with pre-established consent:

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "token_type": "pre_authorized",
    "authorized_recipients": ["org_partner_123"],
    "data_scope": ["full_name", "date_of_birth", "verification_status", "screening_status"],
    "expires_in_days": 30,
    "consent_reference": "consent_agreement_456"
  }'

Token Configuration​

Data Scope Options​

ScopeData Included
full_nameFirst name, last name
date_of_birthDate of birth
nationalityCountry of nationality
addressVerified address
verification_statusDocument verification result
verification_levelLevel achieved (basic/standard/enhanced)
screening_statusAML screening result
risk_scoreCalculated risk score
pep_statusPEP match status

Token Expiration​

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "app_123",
    "expires_in_hours": 1,
    "expires_in_days": null,
    "expires_at": null
  }'
OptionDescriptionUse Case
expires_in_hoursHours until expirationShort-term sharing
expires_in_daysDays until expirationLonger-term access
expires_atSpecific timestampPrecise control

Usage Limits​

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "app_123",
    "max_uses": 5,
    "use_restrictions": {
      "per_recipient_limit": 1,
      "allowed_recipients": ["org_a", "org_b", "org_c"]
    }
  }'

Redeeming Tokens​

Redeem a Token​

Receiving organization redeems the token:

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/redeem \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "gcvt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
  }'

Redemption Response​

{
  "redemption_id": "redemption_789",
  "token_id": "token_abc123",
  "status": "success",
  "verification": {
    "level": "standard",
    "verified_at": "2024-06-15T10:00:00Z",
    "verification_provider": "TrustGate"
  },
  "data": {
    "full_name": "John Doe",
    "date_of_birth": "1985-03-15",
    "verification_status": "verified",
    "screening_status": "clear"
  },
  "redeemed_at": "2025-01-20T15:00:00Z",
  "token_uses_remaining": 0
}

Token Validation​

Validate Without Redeeming​

Check token validity without consuming a use:

curl -X POST https://api.bytrustgate.com/v1/reusable-kyc/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "gcvt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
  }'

Response​

{
  "valid": true,
  "token_id": "token_abc123",
  "expires_at": "2025-01-21T14:30:00Z",
  "uses_remaining": 1,
  "data_scope": ["full_name", "date_of_birth", "verification_status"],
  "verification_level": "standard",
  "can_redeem": true
}

Managing Tokens​

List User's Tokens​

curl -X GET "https://api.bytrustgate.com/v1/reusable-kyc/tokens?applicant_id=app_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

{
  "tokens": [
    {
      "token_id": "token_abc123",
      "status": "active",
      "data_scope": ["full_name", "date_of_birth"],
      "expires_at": "2025-01-21T14:30:00Z",
      "uses_remaining": 1,
      "created_at": "2025-01-20T14:30:00Z"
    },
    {
      "token_id": "token_def456",
      "status": "expired",
      "data_scope": ["full_name", "verification_status"],
      "expired_at": "2025-01-15T10:00:00Z",
      "uses_remaining": 0,
      "created_at": "2025-01-14T10:00:00Z"
    }
  ]
}

Revoke Token​

curl -X DELETE "https://api.bytrustgate.com/v1/reusable-kyc/tokens/token_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "user_request"
  }'

Response​

{
  "token_id": "token_abc123",
  "status": "revoked",
  "revoked_at": "2025-01-20T16:00:00Z",
  "reason": "user_request"
}

Token Security​

Security Features​

FeatureDescription
Cryptographic signingTokens are cryptographically signed
Time-boundAll tokens have expiration
Usage limitsConfigurable maximum uses
Recipient restrictionsLimit which orgs can redeem
Audit trailAll redemptions logged
RevocationCan be revoked at any time

Token Format​

gcvt_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456
│    │    │
│    │    └── Random secure identifier
│    └── Environment (live/test)
└── TrustGate verification token prefix

Webhooks​

Token Events​

Subscribe to token events:

curl -X POST https://api.bytrustgate.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": [
      "reusable_kyc.token.created",
      "reusable_kyc.token.redeemed",
      "reusable_kyc.token.expired",
      "reusable_kyc.token.revoked"
    ]
  }'

Redemption Webhook​

{
  "event": "reusable_kyc.token.redeemed",
  "timestamp": "2025-01-20T15:00:00Z",
  "data": {
    "token_id": "token_abc123",
    "applicant_id": "app_123",
    "redeemed_by": "org_partner_456",
    "data_shared": ["full_name", "date_of_birth", "verification_status"]
  }
}

Next Steps​