Token Scopes
Access tokens in ChainIT APIs are scope-based — every token is limited to exactly the resources and operations you declare. This enforces the principle of least privilege: your application can only touch what it needs.
When requesting an access token, pass the precise scopes required. Tokens are issued only with the permissions allowed by those declared scopes.
Always request the minimum set of scopes your integration needs. Over-permissioned tokens increase your attack surface and may require additional consent steps.
Scope format
Every M2M scope follows a consistent three-part dot-notation:
Anatomy of a scope
e.g. kyb.invite.read reads business invites · kyb.invite.write creates and manages them
product
The service area — e.g. kyb, kyc, file.
feature
The resource within that product — e.g. invite, report.
action
read to query · write to create, update & delete.
Available M2M scopes
Scopes are grouped by product, then by feature. Each feature lists the actions it exposes — read for querying and write for creating, updating, or deleting.
read query & retrieve only
write create, update & delete
KYB — Know Your Business
KYB
Business onboarding, verification, and compliance
The KYB (Know Your Business) scope grants access to business onboarding and verification — verification workflows, organization compliance data, verification status retrieval, and the full onboarding lifecycle. Required for platforms onboarding and managing business entities.
List and retrieve pending and completed business invitations.
Create, update, resend, and delete KYB business invites.
Onboard new businesses through the KYB workflow.
Read organization details, associated users, and business groups.
Read business verification status and UBO task progress.
Edit verification data and trigger reverification.
Generate and read KYB compliance reports.
KYC — Know Your Customer
KYC
Individual identity verification, invites, and reverification
The KYC (Know Your Customer) scope lets applications manage individual identity verification — sending verification requests, retrieving results, managing the verification lifecycle, and generating reports. Required for customer onboarding and compliance validation.
Read KYC invites and associated invite documents.
Create, resend, and delete KYC verification invites.
Read customers and their verified identity information.
Read KYC configuration settings for your organization.
Read KYC verification reports.
Read reverification types and active reverification requests.
Send and cancel KYC reverification requests.
Employee
Employee
Employee records, invites, groups, and reverification
The Employee scope covers workforce identity management — reading employee records, sending and managing invites, viewing employee groups, generating verification reports, and handling reverification requests.
Search, list, and read employee records.
List invite records and view invite details.
Send, update, resend, and remove employee invites.
List and view employee group information.
View and generate employee verification reports.
View reverification requests, statuses, and verification details.
Create, update, send, and cancel reverification requests.
Pactvera
Pactvera
Structured form requests, documents, and templates
The Pactvera scope lets applications create, send, and manage structured form requests used to collect information and documents from users — organizing folders and requests, creating or updating form requests, sending them with associated documents, retrieving documents and request details, managing templates, and canceling or deleting active requests.
List, search, read, and audit Pactvera records.
Create Pactvera records and send new requests.
Read Pactvera documents and folder contents.
Create, update, cancel, and delete documents.
Read Pactvera forms.
Create, update, and delete form requests.
Read Pactvera form and document templates.
Read parties involved in requests.
Read users and audit trail entries.
Mint
Mint
VDT minting, custom data, and event status
The Mint scope enables minting of custom data and transactions (VDTs) on the platform and reading minted VDT details along with their associated event status.
Mint custom data and transactions on the platform.
Read minted VDT details and associated event status.
Product
Product
Product catalog and marketplace management
The Product scope enables management of products listed within the ChainIT ecosystem — creating and managing product records, listing products in marketplaces, updating product metadata, and managing marketplace visibility. Typically used by platforms managing product catalogs.
Create new product records.
List and read existing products.
List and read product categories.
File
File
File uploads and metadata access
The File scope covers secure file handling — requesting presigned URLs to upload files securely and reading the details and metadata of uploaded files.
Request presigned upload URLs to upload files securely.
Read details and metadata of uploaded files.
Requesting scopes
Pass the exact scope strings in the accessTokenScopes array when generating a token:
curl -X POST "https://api.chainit.com/oauth/token" \
-H "Content-Type: application/json" \
-u "{clientId}:{clientSecret}" \
-d '{
"accessTokenScopes": [
"kyb.invite.read",
"kyb.verification.read",
"file.upload.write"
]
}'
The issued token will contain only the granted scopes. Verify them in the decoded payload:
{
"scope": "kyb.invite.read kyb.verification.read file.upload.write",
"permissions": ["kyb.invite.read", "kyb.verification.read", "file.upload.write"],
"azp": "<<your_client_id>>",
"exp": 1715086400
}
Error responses
| Code | Description | Resolution |
|---|---|---|
INVALID_SCOPE | The requested scope is not assigned to your app | Add the scope in Developer Portal → Applications → Scopes |
INSUFFICIENT_SCOPE | Your token lacks the scope required by this endpoint | Re-generate the token with the correct scope included |
Best practices
- Least privilege: Only request the scopes your integration actually uses — not entire products.
- Separate concerns: Use different tokens for different services where possible (e.g. one token for KYB, another for file uploads).
- Validate server-side: Always verify scopes on the API endpoint, not just at the client.
- Rotate credentials: Periodically rotate client secrets and re-issue tokens to limit blast radius if credentials are compromised.
- Monitor usage: Track which scopes are actively used and remove unused ones from your application config.