Permissions

KYC share tokens use a permission system to control which data categories are included when a third party verifies a token. Permissions are set at token creation and cannot be changed afterward.

Available Permissions

View the list of available permissions:

curl -X GET https://api.bytrustgate.com/api/v1/kyc-share/permissions

This is a public endpoint (no authentication required).

Response (200 OK)

{
  "permissions": [
    {
      "key": "basic_info",
      "name": "Basic Info",
      "description": "Name and date of birth"
    },
    {
      "key": "id_verification",
      "name": "ID Verification",
      "description": "ID type, number, and verification status"
    },
    {
      "key": "address",
      "name": "Address",
      "description": "Verified address"
    },
    {
      "key": "screening",
      "name": "Screening",
      "description": "AML/sanctions screening result"
    },
    {
      "key": "documents",
      "name": "Documents",
      "description": "Access to verified documents"
    },
    {
      "key": "full",
      "name": "Full",
      "description": "All verification data"
    }
  ]
}

Permission Details

basic_info

Returns identity information from verified documents:

Field	Type	Description
first_name	string	Applicant's first name
last_name	string	Applicant's last name
date_of_birth	string (ISO date)	Date of birth

id_verification

Returns identity document verification results:

Field	Type	Description
id_type	string	Document type (e.g., passport, drivers_license)
id_number	string	Document number
id_country	string	Issuing country (ISO 3166-1)
id_verified	boolean	Whether document passed verification

address

Returns verified address information:

Field	Type	Description
address	object	Full verified address object

screening

Returns AML/sanctions screening results:

Field	Type	Description
screening_clear	boolean	Whether screening passed with no hits
screening_checked_at	datetime	When screening was last run
has_pep	boolean	Whether applicant matched PEP lists
has_sanctions	boolean	Whether applicant matched sanctions lists

documents

Returns metadata about verified documents (not the document files themselves):

Field	Type	Description
documents	array	List of document metadata objects
documents[].type	string	Document type
documents[].verified_at	datetime	When document was verified
documents[].issuing_country	string	Issuing country

full

Grants all of the above permissions. Equivalent to setting every other permission to true.

How Permissions Work

At Token Creation

When generating a token, you specify which permissions to grant:

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",
    "permissions": {
      "basic_info": true,
      "screening": true,
      "id_verification": false,
      "address": false,
      "documents": false,
      "full": false
    }
  }'

At least one permission must be set to true.

At Verification

When a third party verifies the token, the response only includes fields for the granted permissions. In the example above, the response would include first_name, last_name, date_of_birth, screening_clear, screening_checked_at, has_pep, and has_sanctions — but not id_type, id_number, address, or documents.

Always Included

Regardless of permissions, every verify response includes:

Field	Description
applicant_id	The applicant's UUID
verification_status	The applicant's current status (e.g., approved)
verified_at	When the applicant was verified
token_permissions	Which permissions the token grants
uses_remaining	How many uses are left on the token

Never Shared

These data types are never included in share token responses, regardless of permissions:

• Document images — Original uploaded files
• Biometric data — Selfies, face embeddings, liveness frames
• Device fingerprints — Browser or device information
• Internal case notes — Compliance team notes
• Raw PII fields — Beyond what permissions explicitly allow

Permission Combinations

Common permission configurations for different use cases:

Use Case	Permissions	What Third Party Sees
Identity check	basic_info	Name and DOB only
Full KYC share	full	All verification data
Compliance share	basic_info + screening	Name, DOB, and AML results
Document verification	id_verification + documents	ID details and document metadata

---

Next Steps

• Access Tracking - Monitor who accessed shared data
• Generating Tokens - Token creation and management
• About Reusable KYC - Overview