Set Up Roles via API

This guide shows how to get the permission required by the ATK API. Inside you’ll find:

• A complete catalog of system, token, and add-on roles with one-line descriptions of when they matter.
• The exact methods (client.system.accessManager.grantRole, client.token.grantRole, add-on grant routes) plus request shapes for single or multi-role assignments.
• A minimal workflow (sign in → inspect current roles → grant → verify) you can reuse before running any issuance, collateral, compliance, or add-on automation.

Role types you need to know

System roles — grant with client.system.accessManager.grantRole

These live on the Access Manager contract and control every platform-wide capability. The endpoint accepts one role per call, so run it once for each role you need on a given wallet.

Need to grant several system roles to the same wallet? Call grantRoles once per role.

Token & asset roles — grant with client.token.grantRole

Once a token contract exists, you can grant multiple contract roles in a single request by listing them in the roles array.

Add-on roles — grant through each add-on’s endpoint

Add-on contracts (e.g., the token sale module) expose their own AccessControl roles. Factories usually grant the initial operator automatically, but you can add more operators through the add-on’s dedicated grant-role endpoint (see that add-on’s API reference for the exact route).

How to combine them

• Make sure someone on your team has the admin role so they can perform the system-level grants.
• Every wallet that deploys assets must receive tokenManager.
• If the asset type requires collateral claims or other trusted-issuer checks, grant claimPolicyManager and finish the trusted-issuer registration (Step 3).
• After deployment, each contract you plan to mint from must grant supplyManagement (for issuance) and emergency (for unpausing or operational recovery).
• If the role already exists on your wallet, the grant endpoint will simply return success without duplicates, so it is safe to re-run during audits.

Prerequisites

1. Platform base URL (e.g., https://your-platform.example.com)
2. ATK account with PINCODE enabled (Account Settings → Security)
3. admin system role so you are allowed to grant other roles (or an administrator who can run the system-level grant calls for you)

Step 0: Initialize Client and capture your wallet

Initialize the ORPC client and fetch your wallet address.

Step 1: Check your current system roles

• The roles array should list every system role you expect from the table above.

Step 2: Grant system roles

Replace:

• role: Any value from the system table above (tokenManager, claimPolicyManager, auditor, etc.)

Only admin users can call this endpoint. If you are not an admin, ask someone who is to run the command for your wallet address.

Step 3: Register identity (REQUIRED before minting)

CRITICAL: You must register an identity before you can receive tokens. This is required by the ERC-3643 standard for compliant security tokens.

Parameters:

• wallet: Your wallet address (from Step 0)
• country: ISO 3166-1 alpha-2 country code (e.g., "BE" for Belgium, "US" for USA, "GB" for UK)

What this does:

1. Checks if an identity contract exists for your wallet
2. If identity exists but isn't registered, registers it with a country/jurisdiction
3. If no identity exists, creates an on-chain identity contract and registers it
4. Enables you to receive compliant tokens

Note: The script handles all cases: if you already have an identity and it's registered, it skips both steps. If you have an identity but it's not registered, it will register it. If you don't have an identity, it creates and registers it.

Step 4: Register as a trusted issuer

Skip this section if you don't need to issue claims (e.g., KYC, AML, collateral, accredited investor status) for identities in the system.

What this does:

• Registers you as a trusted issuer authorized to issue claims for specific topics
• Allows you to create claims on identities using client.system.identity.claim.create
• Required for any workflow that needs claim attestations (compliance verification, collateral management, investor classification, etc.)

Parameters:

• issuerAddress: Your identity contract address (from Step 3)
• claimTopicIds: Array of topic IDs you want to issue claims for (get available topics using client.system.claimTopics.topicList)

Note: This registration call requires the claimPolicyManager role from Step 2 and identity from Step 3. Only needs to be done once per issuer/topic combination.

Step 5: Grant token-level roles

Once a token contract is created, give yourself both minting and unpausing permissions in a single request:

Notes:

• To add more token powers (e.g., governance, custodian), include them in the "roles" array from the token table above.
• You can grant roles to multiple operators by changing "address".
• supplyManagement unlocks /mint, while emergency unlocks /unpause.

Step 6: Verify everything at a glance

• System roles: rerun the Step 1 client.system.accessManager.rolesList call and confirm the roles array includes the values you granted.
• Identity: call client.system.identity.me({}) to verify your identity exists
• Token roles: call client.token.holders (or check token details) and confirm the accessControl.supplyManagement and accessControl.emergency arrays contain your wallet address, or simply retry the grantRole call—if you already have the roles, the response will note no change.