# Managing Identities
Source: https://docs.chain.link/ace/guides/identity-manager/manage-identities
Last Updated: 2026-04-06

> For the complete documentation index, see [llms.txt](/llms.txt).

This guide covers how to register, view, update, and archive cross-chain identities (CCIDs) using the ACE Platform UI or the Coordinator API. Identities are the foundation of ACE's credential system — every credential is issued against an identity.

> **NOTE**
>
> This page focuses on identity management. For related workflows, see [Managing
> Registries](/ace/guides/identity-manager/manage-registries), [Managing Credential
> Types](/ace/guides/identity-manager/manage-credential-types), and [Managing
> Credentials](/ace/guides/identity-manager/manage-credentials).

## What are identities (CCIDs)?

A **cross-chain identity (CCID)** aggregates multiple wallet addresses across EVM chains into a single logical entity. Rather than treating each address on each chain as a separate user, ACE maps them all to one CCID. Credentials issued against that CCID are then valid for every linked address on every chain — no re-issuance or bridging required.

Each identity includes:

- **Title** — A human-readable label for internal use only (e.g., "Jane Doe"). This value is never written on-chain.
- **Entity ID** — A unique external identifier that ties the identity back to your system of record (e.g., a KYC provider user ID). This value must be unique within a registry.
- **Registry** — The registry the identity belongs to.
- **On-chain identities** — One or more wallet address + chain selector pairs that map to this CCID on-chain.

For a deeper look at how CCIDs work, how they are generated, and the privacy considerations involved, see [Cross-Chain Identity](/ace/concepts/cross-chain-identity).

## Register an identity

## Bulk import identities

When onboarding many users at once, use the batch endpoint to create multiple identities in a single atomic request. Each identity in the batch follows the same schema as the single-create endpoint, including the optional `credentials` array — so you can register identities and issue credentials in one call.

This feature is **API-only**. In the Platform UI, the **Bulk import via API** option under **+ Add identity** links to this documentation.

Send a `POST` request to `/identities/batch`:

```bash
curl -X POST "https://ace.api.chain.link/v1/identities/batch" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      {
        "title": "Identity A",
        "entity_id": "user-001",
        "registry_id": "<YOUR_REGISTRY_ID>",
        "onchain_identities": [
          {
            "address": "0x1111111111111111111111111111111111111111",
            "chain_selector": "16015286601757825753"
          }
        ],
        "credentials": [
          {
            "credential_type_id": "<YOUR_CREDENTIAL_TYPE_ID>",
            "expires_at": 1800000000
          }
        ]
      },
      {
        "title": "Identity B",
        "entity_id": "user-002",
        "registry_id": "<YOUR_REGISTRY_ID>",
        "onchain_identities": [
          {
            "address": "0x2222222222222222222222222222222222222222",
            "chain_selector": "16015286601757825753"
          },
          {
            "address": "0x3333333333333333333333333333333333333333",
            "chain_selector": "3478487238524512106"
          }
        ]
      }
    ]
  }'
```

The `credentials` array is optional on each identity. The second identity in this example is created without credentials.

> **CAUTION: Atomic operation**
>
> Batch creation is all-or-nothing. If any identity in the batch fails validation, the entire request is rejected and no
> identities are created. Verify each entry before submitting.

## View and search identities

## Update an identity

You can update an identity's title, description, and on-chain address mappings. ACE offers two update approaches: full replacement and partial update.

## Cross-chain identity mapping

A single CCID can span as many chains and addresses as needed. This is the core value proposition of ACE's identity model: one credential verification applies everywhere.

For example, an entity operating wallets on Ethereum Sepolia, Arbitrum Sepolia, and Base Sepolia would have a single identity with three on-chain mappings:

```bash
curl -X POST "https://ace.api.chain.link/v1/identities" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Multi-Chain Operator",
    "entity_id": "operator-xyz-007",
    "registry_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
    "onchain_identities": [
      {
        "chain_selector": "16015286601757825753",
        "address": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      {
        "chain_selector": "3478487238524512106",
        "address": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      },
      {
        "chain_selector": "10344971235874465080",
        "address": "0xcccccccccccccccccccccccccccccccccccccccc"
      }
    ]
  }'
```

| Chain            | Chain Selector         | Address         |
| :--------------- | :--------------------- | :-------------- |
| Ethereum Sepolia | `16015286601757825753` | `0xaaaa...aaaa` |
| Arbitrum Sepolia | `3478487238524512106`  | `0xbbbb...bbbb` |
| Base Sepolia     | `10344971235874465080` | `0xcccc...cccc` |

All three addresses resolve to the same CCID. A credential issued against this identity — such as a KYC attestation — is valid for all three addresses across all three chains. When any of these addresses interacts with a policy-protected contract, the policy resolves the address to the shared CCID and checks credentials from there.

To add or remove chains later, use the [full update (PUT)](#full-update-put) endpoint with the updated list of on-chain identities.

## Archive an identity

Archiving marks an identity as inactive. Archived identities are retained for audit purposes but are no longer considered active.

> **CAUTION: Archive credentials first**
>
> Before archiving an identity, archive or revoke any active credentials associated with it. Credentials linked to an
> archived identity may no longer be evaluated correctly by policies. See [Managing
> Credentials](/ace/guides/identity-manager/manage-credentials) for credential lifecycle management.