Identity Manager Quick Start

This guide walks you through the Identity Manager — the ACE component for managing identity registries, registering cross-chain identities (CCIDs), and issuing credentials such as Proof of Identity, accreditation proofs, or sanctions clearance. By the end you will have identities registered and credentials issued on a supported network.

1. Prerequisites

  • Familiarity with Cross-Chain Identity concepts — CCIDs, credential registries, credential types, and credential sources
  • Must-read before proceeding: Signing & Ownership Model — understand how ACE manages keys, who owns what, and how the delegated trust model works

2. Account setup

Complete the Account Setup steps — organization creation, API key generation, and CRE Connect Wallet deployment — before proceeding.

3. Set up your registries

A registry is the top-level resource that groups an identity registry and a credential registry, deployed together on each chain you operate on.

  • The identity registry maps wallet addresses to cross-chain identities (CCIDs)
  • The credential registry stores credential attestations linked to those CCIDs

See Managing Registries for full details.

  1. In the Chainlink App, navigate to Compliance > Identity Manager in the left sidebar.
  2. Click the Add a new registry card.
  3. Enter a Registry name and optional Description, then click Continue.
  4. Select the networks you want to deploy the registry to, then click Deploy registry. ACE deploys the identity and credential registry contracts on each selected chain.
  5. Once deployed, click the gear icon next to the registry name to view the on-chain contract addresses for each identity and credential registry.

    Click the gear icon to view registry contract addresses.

Create a registry with a POST request:

curl -X POST "https://ace.api.chain.link/v1/registries" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Registry",
    "description": "Identity and credential registries for my organization",
    "identity_registries": [
      { "name": "Identity Registry - Sepolia", "description": "Identity registry on Ethereum Sepolia", "chain_selector": "16015286601757825753" },
      { "name": "Identity Registry - Arbitrum", "description": "Identity registry on Arbitrum Sepolia", "chain_selector": "3478487238524512106" }
    ],
    "credential_registries": [
      { "name": "Credential Registry - Sepolia", "description": "Credential registry on Ethereum Sepolia", "chain_selector": "16015286601757825753" },
      { "name": "Credential Registry - Arbitrum", "description": "Credential registry on Arbitrum Sepolia", "chain_selector": "3478487238524512106" }
    ]
  }'

ACE deploys the identity and credential registry contracts on each specified chain. The response includes the registry id you will use in subsequent steps.

4. Define credential types

Credential types represent the categories of attestation you issue — for example, Proof of Identity, accredited investor, or sanctions clearance. Each credential type is scoped to a specific registry and identified by a credential_type string that gets hashed on-chain to a credential_type_hash. This value is hashed using keccak256 — the standard cryptographic hash function used by Ethereum and EVM-compatible blockchains — and the resulting credential_type_hash is what gets recorded on-chain and referenced by policies.

  1. In the Chainlink App, navigate to Compliance > Identity Manager and click on your registry card.
  2. Select the Credential types tab, then click + Add credential type.
  3. In the drawer that opens, fill in:
    • Internal Display Name — A label used by your team to identify and track this credential (not stored on-chain).
    • Credential — The credential type string (e.g., proof_of_identity_basic).
    • Description — Optional description.
  4. Click Save.

Create a credential type with a POST request. The registry_id was returned in the response when you created your registry. To retrieve it later, list your registries with GET /registries.

curl -X POST "https://ace.api.chain.link/v1/credential-types" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "registry_id": "<YOUR_REGISTRY_ID>",
    "title": "KYC Verification",
    "credential_type": "kyc_basic",
    "description": "Basic KYC identity verification"
  }'

You can list existing credential types for a registry at any time:

curl -X GET "https://ace.api.chain.link/v1/credential-types?registry_id=a1b2c3d4-5678-9abc-def0-1234567890ab" \
  -H "Authorization: Apikey <API_KEY>"

5. Register identities and issue credentials

A cross-chain identity (CCID) aggregates one or more wallet addresses across EVM chains into a single logical entity. When you register an identity, you provide the on-chain addresses that belong to that entity and ACE writes the mapping into the identity registry on each relevant chain.

A single CCID can span multiple chains and addresses — for example, one entity might have wallets on Ethereum, Arbitrum, and Avalanche that all resolve to the same CCID.

Credentials are attestations linked to a registered identity. During Beta, ACE uses an attestation-only model — the Identity Manager asserts that a credential holds for a given CCID, and the credential registry records that attestation on-chain.

The Platform UI lets you register an identity and assign credentials in a single flow:

  1. In the Chainlink App, navigate to Compliance > Identity Manager and click on your registry card.
  2. Click + Add identity.
  3. Fill in:
    • Alias — An internal name for this identity. This is never written on-chain.
    • Metadata — Optional internal reference data, also never written on-chain.
  4. Click Continue.
  5. Enter the wallet address(es) for the identity on each network where your registry is deployed. Click Add more to add multiple addresses per network or addresses on different networks.
  6. Click Continue.
  7. Assign credential types to this identity and set an expiration date for each credential. The expiration is optional — if omitted, the credential does not expire.
  8. Click Deploy identity. ACE registers the identity and issues the assigned credentials on-chain in one transaction.

Register an identity and issue credentials in a single POST request by including the optional credentials array:

curl -X POST "https://ace.api.chain.link/v1/identities" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Identity",
    "entity_id": "user-12345",
    "registry_id": "<YOUR_REGISTRY_ID>",
    "description": "Test identity for getting started",
    "onchain_identities": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "chain_selector": "16015286601757825753"
      }
    ],
    "credentials": [
      {
        "credential_type_id": "<YOUR_CREDENTIAL_TYPE_ID>",
        "expires_at": 1800000000
      }
    ]
  }'

The credentials array is optional — omit it to register an identity without credentials. Within each credential, expires_at is also optional (a Unix timestamp); if omitted, the credential does not expire.

You can also issue credentials separately after the identity is created using POST /credentials. See Managing Credentials for details.

6. Verify via Reporting

After issuing credentials, confirm they are visible and queryable through the Reporting Manager. The Reporting Manager provides a read-only view of all identities and credentials across your registries, which Policy Managers rely on when evaluating identity-based policies at transaction time.

  • Open the Reporting API to query credentials by identity, entity, or registry
  • See Reporting for details on how reporting data flows into policy evaluation

Once credentials appear in reporting, Policy Managers can reference them in identity-based policies such as the Credential Registry Identity Validator.

7. What's next

Explore the detailed guides for each Identity Manager workflow:

Get the latest Chainlink content straight to your inbox.