Identities

Create, rotate, and manage cryptographic identities.

Identity dataclass

Identity(did: str, _key_alias: str, label: str, repo_path: str, public_key: str)

An Auths identity (represents a did:keri: identifier).

did instance-attribute

did: str

The KERI decentralized identifier (e.g. did:keri:EXq5...).

label instance-attribute

label: str

Human-readable label (e.g. "laptop", "main").

repo_path instance-attribute

repo_path: str

Path to the Git identity repository.

public_key instance-attribute

public_key: str

Hex-encoded Ed25519 public key.

AgentIdentity dataclass

AgentIdentity(did: str, _key_alias: str, attestation: str, public_key: str)

Standalone agent identity (did:keri:). Created via identities.create_agent().

did instance-attribute

did: str

The agent's KERI decentralized identifier.

attestation instance-attribute

attestation: str

JSON-serialized attestation binding the agent to its capabilities.

public_key instance-attribute

public_key: str

Hex-encoded Ed25519 public key.

DelegatedAgent dataclass

DelegatedAgent(did: str, _key_alias: str, attestation: str, public_key: str)

Agent delegated under a parent identity (did:key:). Created via identities.delegate_agent().

did instance-attribute

did: str

The delegated agent's device-level identifier (did:key:z...).

attestation instance-attribute

attestation: str

JSON-serialized delegation attestation signed by the parent identity.

public_key instance-attribute

public_key: str

Hex-encoded Ed25519 public key.

IdentityService

IdentityService(client: Auths)

Resource service for identity operations.

Examples:

auths = Auths()
identity = auths.identities.create(label="laptop")
agent = auths.identities.delegate_agent(identity.did, name="ci-bot", capabilities=["sign"])

create

create(label: str = 'main', repo_path: str | None = None, passphrase: str | None = None) -> Identity

Create a new identity.

Parameters:

• label (str, default: 'main' ) –

  Human-readable label for this identity (default: "main").

• repo_path (str | None, default: None ) –

  Git repo path (default: client's repo_path).

• passphrase (str | None, default: None ) –

  Key passphrase (default: client's passphrase or AUTHS_PASSPHRASE env var).

Returns:

• Identity –

  Identity with the DID, public key, and key alias.

Raises:

• IdentityError –

  If an identity with this alias already exists.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

identity = auths.identities.create(label="laptop")

rotate

rotate(identity_did: str, *, passphrase: str | None = None) -> IdentityRotationResult

Rotate an identity's keys using the KERI pre-rotation ceremony.

This is a single atomic operation. If any step fails, the previous key remains active and no partial state is written.

After rotation: - Old attestations remain valid (verified via Key Event Log history) - New signing operations use the rotated key automatically - Device links are unaffected (bound to DID, not key)

Parameters:

• identity_did (str) –

  The KERI DID of the identity to rotate.

• passphrase (str | None, default: None ) –

  Optional passphrase for keychain access.

Returns:

• IdentityRotationResult –

  IdentityRotationResult with the new key fingerprint and sequence number.

Raises:

• IdentityError –

  If the identity does not exist or rotation fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

result = auths.identities.rotate(identity.did)
print(f"Rotated to sequence {result.sequence}")

create_agent

create_agent(name: str, capabilities: list[str], passphrase: str | None = None) -> AgentIdentity

Create a standalone agent identity (did:keri:).

Parameters:

• name (str) –

  Human-readable agent name.

• capabilities (list[str]) –

  List of capabilities (e.g., ["sign", "verify"]).

• passphrase (str | None, default: None ) –

  Key passphrase override.

Returns:

• AgentIdentity –

  AgentIdentity with the agent DID, attestation, and public key.

Raises:

• IdentityError –

  If agent creation fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

agent = auths.identities.create_agent("ci-bot", ["sign"])

delegate_agent

delegate_agent(identity_did: str, name: str, capabilities: list[str], expires_in: int | None = None, passphrase: str | None = None) -> DelegatedAgent

Delegate an agent under an identity (did:key:).

Parameters:

• identity_did (str) –

  The parent identity's DID.

• name (str) –

  Human-readable agent name.

• capabilities (list[str]) –

  List of capabilities (e.g., ["sign", "verify"]).

• expires_in (int | None, default: None ) –

  Duration in seconds until expiration (per RFC 6749).

• passphrase (str | None, default: None ) –

  Key passphrase override.

Returns:

• DelegatedAgent –

  DelegatedAgent with the agent DID, delegation attestation, and public key.

Raises:

• IdentityError –

  If the parent identity doesn't exist or delegation fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

agent = auths.identities.delegate_agent(identity.did, "ci-bot", ["sign"])

IdentityRotationResult dataclass

IdentityRotationResult(controller_did: str, new_key_fingerprint: str, previous_key_fingerprint: str, sequence: int)

Result of a KERI key rotation ceremony.

After rotation, old attestations remain valid — verifiers walk the Key Event Log to find the key that was active at signing time.

controller_did instance-attribute

controller_did: str

The identity's KERI DID.

new_key_fingerprint instance-attribute

new_key_fingerprint: str

Fingerprint of the newly rotated-in key.

previous_key_fingerprint instance-attribute

previous_key_fingerprint: str

Fingerprint of the key that was rotated out.

sequence instance-attribute

sequence: int

KERI sequence number after rotation.