Identity keys API reference

When an auditor or integration needs to confirm who controls an identity contract, the question is concrete: which keys are registered on it right now, what is each key allowed to do, and when was it added? The identity keys endpoint answers it. It lists the ERC-734 keys on a single identity contract, with each key's purpose, key type, and the block and transaction that recorded it.

The endpoint is read-only. It reports the keys the identity registry already tracks for the contract. It does not add, rotate, or remove keys. ERC-734 keys are on-chain public data, so the list reflects the live key set the index has observed for that identity. For authentication and base URL setup, see Getting started. For the wider compliance API map, see Compliance API route map.

Endpoint

The identityAddress path parameter is the address of an indexed identity contract. That can be a system organization identity, a user wallet identity, a claim issuer identity, or any other contract identity the active system tracks. The endpoint uses the collection envelope: data holds the page of keys, meta carries the total count and facet breakdowns, and links carries pagination links. The active organization and system context bounds every read, as described in Organization and system scope.

curl --globoff "https://your-platform.example.com/api/v2/system/identities/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/keys?filter[purpose]=claimSigner" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "keyHash": "0x9d8a5b6f3a7f8e2c1d4b5a6e7f8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c",
      "purpose": "claimSigner",
      "keyType": "ecdsa",
      "createdAt": "2026-05-06T12:34:56.000Z",
      "createdAtBlock": "12345678",
      "createdAtTxHash": "0xabc1230000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "purpose": [{ "value": "claimSigner", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/keys?page[offset]=0&page[limit]=50",
    "first": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/keys?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/identities/0x71c7656ec7ab88b098defb751b7401b5f6d8976f/keys?page[offset]=0&page[limit]=50"
  }
}

When the identity address has no indexed keys, data is an empty array and meta.total is 0. The endpoint does not return a not-found error for an unknown address; it returns an empty page.

Key fields

Each row describes one ERC-734 key on the identity contract.

The createdAtBlock and createdAtTxHash fields give an auditor a verifiable anchor: the exact transaction that added each key, so the on-chain record can be checked independently.

Key purposes

The purpose value decodes the numeric ERC-734 purpose into a label.

For a claim issuer, the claimSigner keys are the ones that matter to a verifier. The asset layer checks that the key which signed a claim holds the claim-signing purpose on the issuer's identity at the moment of attestation. Listing the keys lets a reviewer confirm which signing keys an issuer holds. For the wider model, see Claims and identity.

Query controls

The meta.facets block reports counts for the purpose and keyType values across the current filtered set, so an interface can show option badges without a second call. The counts reflect the active filters.

Who can read identity keys

Reading the identity keys list requires one of the following roles for the active system: Identity manager, System manager, or Claim issuer. A caller without one of these roles receives a permission error. The same role boundary applies to the Registered identities API, so a caller that can list registered identities can also inspect the keys on any of them.

The endpoint reads indexed on-chain data and does not make a live chain call. Any identity address indexed on the active system's chain is queryable. The list reflects the key set the index has observed, so a key added in a very recent block may take a short time to appear.

Related pages

• Registered identities API
• Compliance API route map
• Claims and identity
• Identity and compliance
• Configure trusted issuers