Set Up Roles in ATK

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 endpoints (/api/system/access-manager/grant-roles, /api/token/grant-role, 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 `POST /api/system/access-manager/grant-roles`

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.

Role	What it controls	When to grant it
`admin`	Root authority that can grant or revoke every other system role.	Keep on the platform ops account; required before you can delegate the rest.
`systemManager`	Core system configuration (upgrades, registering factories/modules).	Rarely granted to EOAs; only to the ops team running the deployment.
`identityManager`	Identity registry maintenance (register/recover identities, onboarding).	Needed by compliance/onboarding teams managing identities outside the UI.
`tokenManager`	Token factory calls such as `/api/token/create`.	Every wallet that deploys assets needs this regardless of asset class.
`complianceManager`	Global compliance module setup, bypass lists, enforcement toggles.	Use when configuring custom compliance flows or allowlists.
`addonManager`	Registering and configuring add-on factories.	Needed when rolling out optional protocol extensions (token sale, funds, etc.).
`claimPolicyManager`	Trusted issuer + claim topic management via `/api/system/trusted-issuers`.	Required for any workflow that checks collateral/KYC claims before minting.
`claimIssuer`	Permission to create claims on identities (trust decided separately).	Grant to auditors or service providers that issue attestations.
`organisationIdentityManager`	Organisation-level claim management (KYC/AML/licenses).	Use for corporate ops that maintain entity credentials.
`auditor`	Read-only access to permissions, identities, and audit state.	Assign to internal/external auditors that need visibility without write access.
`systemModule`	Lets a module contract manage other system components.	Granted to module contracts themselves during deployment.
`identityRegistryModule`	Administrative control of the identity registry module.	Granted to module contracts or tooling that automate registry tasks.
`tokenFactoryRegistryModule`	Manages token factory registries.	Usually assigned to module contracts, not EOAs.
`tokenFactoryModule`	Direct control over token factory modules.	Needed by automation or module contracts deploying assets.
`addonRegistryModule`	Controls the add-on registry module.	Given to registry automation or governance contracts.
`addonModule`	Lets an add-on module register instances.	Granted to the add-on module contracts themselves.
`trustedIssuersMetaRegistryModule`	Manages the trusted issuer meta-registry.	Assigned to system automation that syncs issuer lists across modules.

Need to grant several system roles to the same wallet? Call /api/system/access-manager/grant-roles once per role; each payload only accepts a single role string.

Token & asset roles — grant with `POST /api/token/grant-role`

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

Role	What it controls	When to grant it
`governance`	Token policy, verification, and compliance settings.	Assign to the team that tunes compliance modules or governance parameters.
`supplyManagement`	Mint/burn permissions via `/api/token/{contract}/mint`.	Required for every operator that issues, redeems, or retires supply.
`custodian`	Freezes, forced transfers, and asset recovery.	Grant to custody/operations teams responsible for interventions.
`emergency`	Pause/unpause and ERC20 recovery actions.	Needed for the team that handles incident response or post-deploy unpausing.

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).

Role	Contract scope	When to grant it
`saleAdmin`	Configures and operates a token sale (pricing, limits, lifecycle).	Give to the primary issuance lead for each sale contract.
`fundsManager`	Withdraws proceeds collected by a token sale add-on.	Assign to treasury/custody wallets that sweep sale revenue.

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

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

curl -s -X POST YOUR_PLATFORM_URL/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD"
  }'

curl -s YOUR_PLATFORM_URL/api/user/me \
  -b cookies.txt | tee user-me.json

Copy the wallet value out of user-me.json. You will pass it into every grant call below.
Delete user-me.json when you are done; it just helps you keep track of the response.

Step 1: Check your current system roles

curl -s YOUR_PLATFORM_URL/api/system/access-manager/roles \
  -b cookies.txt | tee roles.json

Find the object where account equals your wallet. The roles array should list every system role you expect from the table above.
Remove roles.json after you finish reviewing it.

Step 2: Grant system roles

curl -v -X POST YOUR_PLATFORM_URL/api/system/access-manager/grant-roles \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "address": "YOUR_WALLET_ADDRESS",
    "role": "ROLE_NAME",
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

Replace:

ROLE_NAME: Any value from the system table above (tokenManager, claimPolicyManager, auditor, etc.)
YOUR_PINCODE: PINCODE from your ATK profile

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 as a trusted issuer (collateral workflows)

Skip this section if your asset class never calls /api/token/{contract}/update-collateral or any endpoint that checks collateral claims.

# Identity contract (issuer address)
curl -s YOUR_PLATFORM_URL/api/system/identity/me \
  -b cookies.txt | tee identity.json

# Collateral topic ID
curl -s YOUR_PLATFORM_URL/api/system/claim-topics \
  -b cookies.txt | tee claim-topics.json

# Register yourself for the collateral topic
curl -v -X POST YOUR_PLATFORM_URL/api/system/trusted-issuers \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "issuerAddress": "YOUR_IDENTITY_ADDRESS",
    "claimTopicIds": ["COLLATERAL_TOPIC_ID"],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

In identity.json, copy the id field; that is your issuer address.
In claim-topics.json, locate the entry with "name": "collateral" and copy its topicId.
This registration call requires the claimPolicyManager role from Step 2 and only needs to be done once per issuer/topic.
You can delete the helper JSON files once you record the values.

Step 4: Grant token-level roles

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

curl -v -X POST YOUR_PLATFORM_URL/api/token/grant-role \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "contract": "YOUR_TOKEN_CONTRACT",
    "address": "YOUR_WALLET_ADDRESS",
    "roles": ["supplyManagement", "emergency"],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

Notes:

contract stays in the request body—do not put it in the URL.
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 5: Verify everything at a glance

System roles: rerun the Step 1 GET /api/system/access-manager/roles call and confirm the roles array includes the values you granted.
Token roles: call GET /api/token/YOUR_TOKEN_CONTRACT and confirm the accessControl.supplyManagement and accessControl.emergency arrays contain your wallet address, or simply retry the grant-role call—if you already have the roles, the response will note no change.

Set Up Roles via API