Managing Credential Types

Credential types define the categories of attestations you can issue to cross-chain identities (CCIDs). Each credential type represents a distinct kind of verification — for example, KYC completion, accredited investor status, or sanctions clearance. When you create a credential type, the credential_type string you provide is hashed to produce a credential_type_hash that policy contracts reference on-chain.

Credential types are scoped to a specific credential registry. Before creating credential types, make sure your registries are set up.

A credential type can optionally be linked to a data schema, which lets the credentials you issue against it carry structured data (for example, a jurisdiction code). See Typed credentials with data schemas below.

What is a credential type?

A credential type is a string you define to represent a specific compliance check or verification. This string is hashed and registered on-chain, so it cannot be changed after creation. You can create any credential types that match your requirements — for example:

Credential type string	Use case
`PROOF_OF_IDENTITY`	Identity verification
`PROOF_OF_FUNDS`	Source of funds or reserves check
`AML_CHECK`	Anti-money-laundering screening result

The credential_type string is case-sensitive and must be unique within a registry.

Define a credential type

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

The response includes the generated credential_type_id and the credential_type_hash derived from your credential_type string.

Understand credential type hashes

When you create a credential type, ACE hashes the credential_type string to produce a deterministic credential_type_hash. This hash is what gets written on-chain and what policy contracts use when evaluating identity-based rules.

credential_type string    →    credential_type_hash         →    on-chain reference
"KYC"                     →    0x7a8b...3f21                →    used by policy contracts

Because the hash is derived from the string, choosing your credential_type strings carefully matters — they cannot be changed after creation. Policy contracts such as the Credential Registry Identity Validator reference credentials by their credential_type_hash when checking whether an identity holds a required attestation.

Typed credentials with data schemas

By default, credentials are attestation-only: they record that an identity holds a credential of a given type, with no additional data. You can instead create a typed credential type by linking it to a data schema. Credentials issued against a typed credential type carry structured data (validated against the schema), which policies can then evaluate through a Data Validator.

A data schema is a reusable definition of the shape and format of a credential's data. ACE provides shared, ready-to-use schemas — the first is an ISO 3166-1 alpha-2 country code schema for jurisdiction use cases (an array of two-letter country codes such as US, CA, GB).

To make a credential type typed, pass a data_schema_id when you create it. The ISO 3166-1 alpha-2 country code data schema ID is:

fb786cd7-6397-4ac6-790c-35746f343cad

curl -X POST "https://ace.api.chain.link/v1/credential-types" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "registry_id": "<REGISTRY_ID>",
    "title": "Jurisdiction",
    "credential_type": "common.country",
    "description": "Holder jurisdiction as ISO 3166-1 alpha-2 country codes",
    "data_schema_id": "fb786cd7-6397-4ac6-790c-35746f343cad"
  }'

Once a credential type is linked to a data schema, every credential you issue against it must include credential_data matching that schema — see Issue a credential with data.

View credential types

List credential types with a GET request. Use the registry_id query parameter to filter by registry:

curl "https://ace.api.chain.link/v1/credential-types?registry_id=<REGISTRY_ID>&page=1&page_size=25" \
  -H "Authorization: Apikey <API_KEY>"

To retrieve a single credential type by ID:

curl "https://ace.api.chain.link/v1/credential-types/<CREDENTIAL_TYPE_ID>" \
  -H "Authorization: Apikey <API_KEY>"

Update a credential type

You can update a credential type's title and description. The credential_type string and credential_type_hash cannot be changed.

Update a credential type with a PUT request:

curl -X PUT "https://ace.api.chain.link/v1/credential-types/<CREDENTIAL_TYPE_ID>" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "KYC Verification (Enhanced)",
    "description": "Enhanced KYC verification including document and liveness checks"
  }'

You can also make partial updates with a PATCH request:

curl -X PATCH "https://ace.api.chain.link/v1/credential-types/<CREDENTIAL_TYPE_ID>" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for KYC verification"
  }'

Archive a credential type

Archiving a credential type prevents new credentials of that type from being issued. Existing credentials remain valid until they are individually archived or expire.

Archive a credential type with a PATCH request:

curl -X PATCH "https://ace.api.chain.link/v1/credential-types/<CREDENTIAL_TYPE_ID>" \
  -H "Authorization: Apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "archived"
  }'

If active credentials still reference the type, the request returns an error. Archive all associated credentials first, then retry.

Cross-Chain Identity — conceptual overview of CCIDs, registries, and credential types
Managing Credentials — issue, revoke, and manage credentials linked to CCIDs
Managing Registries — view and manage identity and credential registry deployments
Credential Registry Identity Validator Policy — the policy contract that checks credentials on-chain

Managing Credential Types

Get the latest Chainlink content straight to your inbox.