Generating Tokens

KYC share tokens are secure, time-limited credentials that allow third parties to view a user's verification results.

Generate a Token

Create a share token for an approved applicant.

curl -X POST https://api.bytrustgate.com/api/v1/kyc-share/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "shared_with": "Partner Company Inc",
    "shared_with_email": "compliance@partner.com",
    "purpose": "Account opening verification",
    "permissions": {
      "basic_info": true,
      "id_verification": true,
      "screening": true,
      "address": false,
      "documents": false,
      "full": false
    },
    "expires_days": 7,
    "max_uses": 1
  }'

Request Parameters

Parameter	Type	Required	Description
applicant_id	UUID	Yes	The applicant whose data will be shared. Must have status: "approved".
shared_with	string	Yes	Name of the company or entity receiving the data (1-255 chars).
shared_with_email	string	No	Contact email for the recipient.
purpose	string	No	Reason for sharing (max 500 chars).
permissions	object	Yes	Which data categories to include. At least one must be true.
expires_days	integer	No	Days until expiration. Default: 30. Max: 90.
max_uses	integer	No	Maximum number of times the token can be verified. Default: 1. Max: 10.

Response (201 Created)

{
  "token": "aB3dEfGhIjKlMnOpQrStUvWxYz012345678901234",
  "token_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "token_prefix": "aB3dEfGh",
  "expires_at": "2026-02-11T14:30:00Z",
  "max_uses": 1,
  "permissions": {
    "basic_info": true,
    "id_verification": true,
    "screening": true,
    "address": false,
    "documents": false,
    "full": false
  },
  "shared_with": "Partner Company Inc"
}

caution

The token value is shown only once in this response. It is not stored — only its SHA-256 hash is kept. Save the token immediately.

Errors

Status	Error	Description
400	ApplicantNotApprovedError	Applicant must have status: "approved"
400	KYCShareError	Invalid permissions or configuration
404	Not Found	Applicant not found or belongs to different tenant

Verify a Token

Third parties use this public endpoint (no authentication required) to retrieve shared verification data.

curl -X POST https://api.bytrustgate.com/api/v1/kyc-share/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "aB3dEfGhIjKlMnOpQrStUvWxYz012345678901234"
  }'

Request Parameters

Parameter	Type	Required	Description
token	string	Yes	The share token (minimum 20 characters).

Response (200 OK)

The response includes only the data categories allowed by the token's permissions:

{
  "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_status": "approved",
  "verified_at": "2026-01-15T10:00:00Z",

  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1985-03-15",

  "id_type": "passport",
  "id_number": "AB1234567",
  "id_country": "US",
  "id_verified": true,

  "screening_clear": true,
  "screening_checked_at": "2026-01-15T10:05:00Z",
  "has_pep": false,
  "has_sanctions": false,

  "token_permissions": {
    "basic_info": true,
    "id_verification": true,
    "screening": true,
    "address": false,
    "documents": false,
    "full": false
  },
  "uses_remaining": 0
}

Fields like address, documents are omitted because those permissions are false on this token.

Errors

Status	Error	Description
404	TokenInvalidError	Token not found or invalid
410	TokenExpiredError	Token has expired
410	TokenRevokedError	Token has been revoked
410	TokenExhaustedError	Token has reached its max uses

Each successful verification increments the token's use count. When use_count reaches max_uses, subsequent calls return 410 Gone.

List Tokens

List all share tokens for an applicant.

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

Query Parameters

Parameter	Type	Default	Description
include_expired	boolean	false	Include expired and exhausted tokens

Response (200 OK)

{
  "tokens": [
    {
      "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
      "token_prefix": "aB3dEfGh",
      "shared_with": "Partner Company Inc",
      "shared_with_email": "compliance@partner.com",
      "purpose": "Account opening verification",
      "permissions": {
        "basic_info": true,
        "id_verification": true,
        "screening": true,
        "address": false,
        "documents": false,
        "full": false
      },
      "expires_at": "2026-02-11T14:30:00Z",
      "max_uses": 1,
      "use_count": 0,
      "uses_remaining": 1,
      "status": "active",
      "revoked_at": null,
      "revoked_reason": null,
      "created_at": "2026-02-04T14:30:00Z"
    }
  ],
  "total": 1
}

Token Status Values

Status	Description
active	Token is valid and has remaining uses
expired	Token has passed its expires_at time
exhausted	Token has reached its max_uses limit
revoked	Token was manually revoked

Revoke a Token

Immediately invalidate a token. Any subsequent verify calls will return 410 Gone.

curl -X POST "https://api.bytrustgate.com/api/v1/kyc-share/revoke/d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User requested revocation"
  }'

Request Parameters

Parameter	Type	Required	Description
reason	string	No	Reason for revocation (max 255 chars). Stored for audit.

Response

204 No Content on success.

Token Security

How Tokens Work

1. Token is generated using secrets.token_urlsafe(32) — a cryptographically secure random string
2. The SHA-256 hash of the token is stored in the database
3. The actual token is returned once in the creation response and never stored
4. On verification, the provided token is hashed and matched against the database
5. The first 8 characters are stored as token_prefix for identification in the UI

Limits

Limit	Value
Maximum expiry	90 days
Default expiry	30 days
Maximum uses	10
Default uses	1 (single-use)
Minimum token length for verification	20 characters

---

Next Steps

• Permissions - Detailed permission reference
• Access Tracking - Monitor who accessed shared data
• About Reusable KYC - Overview