Client

The main entry point for the Auths Python SDK.

Auths

Auths(repo_path: str = '~/.auths', passphrase: str | None = None)

Auths SDK client — decentralized identity for developers.

Examples:

auths = Auths()
result = auths.verify(attestation_json=data, issuer_key=key)
sig = auths.sign(b"hello", private_key=key_hex)

verify

verify(attestation_json: str, issuer_key: str, required_capability: str | None = None, at: str | None = None) -> VerificationResult

Verify a single attestation, optionally at a specific historical timestamp.

Parameters:

• attestation_json (str) –

  The attestation JSON string.

• issuer_key (str) –

  Issuer's public key hex.

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

  If set, also verify the attestation grants this capability.

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

  RFC 3339 timestamp to verify against (e.g., "2024-06-15T00:00:00Z"). When set, checks validity at that point in time instead of now.

Returns:

• VerificationResult –

  VerificationResult with validity status and details.

Raises:

• VerificationError –

  If the attestation signature is invalid or expired.

• CryptoError –

  If the issuer key is malformed.

Examples:

result = auths.verify(att_json, key, at="2024-06-15T00:00:00Z",
                      required_capability="deploy:staging")

verify_chain

verify_chain(attestations: list[str], root_key: str, required_capability: str | None = None, witnesses: WitnessConfig | None = None) -> VerificationReport

Verify an attestation chain, optionally with witness quorum.

Parameters:

• attestations (list[str]) –

  List of attestation JSON strings, ordered root-to-leaf.

• root_key (str) –

  Root identity's public key hex.

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

  If set, verify the chain grants this capability.

• witnesses (WitnessConfig | None, default: None ) –

  If set, enforces witness receipt quorum.

Returns:

• VerificationReport –

  VerificationReport with per-link results and overall validity.

Raises:

• VerificationError –

  If any link in the chain fails verification.

Examples:

report = auths.verify_chain(chain, root_key, witnesses=config)

verify_device

verify_device(identity_did: str, device_did: str, attestations: list[str], identity_key: str) -> VerificationReport

Verify device authorization against an identity.

Parameters:

• identity_did (str) –

  The parent identity's DID.

• device_did (str) –

  The device DID to verify.

• attestations (list[str]) –

  Attestation chain JSON strings.

• identity_key (str) –

  Identity's public key hex.

Returns:

• VerificationReport –

  VerificationReport confirming the device is authorized.

Raises:

• VerificationError –

  If the device authorization is invalid or revoked.

sign

sign(message: bytes, private_key: str) -> str

Sign raw bytes with a private key.

Parameters:

• message (bytes) –

  Bytes to sign.

• private_key (str) –

  Hex-encoded Ed25519 private key.

Returns:

• str –

  Hex-encoded Ed25519 signature.

Raises:

• CryptoError –

  If the private key is invalid or signing fails.

sign_action

sign_action(action_type: str, payload: str, identity_did: str, private_key: str) -> str

Sign an action envelope.

Parameters:

• action_type (str) –

  Action type string.

• payload (str) –

  JSON payload string.

• identity_did (str) –

  The signer's DID.

• private_key (str) –

  Hex-encoded Ed25519 private key.

Returns:

• str –

  JSON-serialized signed action envelope.

Raises:

• CryptoError –

  If signing fails.

verify_action

verify_action(envelope_json: str, public_key: str) -> VerificationResult

Verify an action envelope signature.

Parameters:

• envelope_json (str) –

  JSON-serialized signed action envelope.

• public_key (str) –

  Hex-encoded Ed25519 public key of the signer.

Returns:

• VerificationResult –

  VerificationResult with validity status.

Raises:

• VerificationError –

  If the envelope signature is invalid.

sign_as

sign_as(message: bytes, identity: str, passphrase: str | None = None) -> str

Sign bytes using a keychain-stored identity key.

Parameters:

• message (bytes) –

  Bytes to sign.

• identity (str) –

  The identity DID (did:keri:...) whose key to use.

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

  Override passphrase (default: client passphrase or AUTHS_PASSPHRASE).

Returns:

• str –

  Hex-encoded Ed25519 signature.

Raises:

• CryptoError –

  If the key is not found or signing fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

identity = auths.identities.create(label="laptop")
sig = auths.sign_as(b"hello", identity=identity.did)

sign_action_as

sign_action_as(action_type: str, payload: str, identity: str, passphrase: str | None = None) -> str

Sign an action envelope using a keychain-stored identity key.

Parameters:

• action_type (str) –

  Action type string.

• payload (str) –

  JSON payload string.

• identity (str) –

  The identity DID whose key to use.

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

  Override passphrase.

Returns:

• str –

  JSON-serialized signed action envelope.

Raises:

• CryptoError –

  If signing fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

envelope = auths.sign_action_as("deploy", payload_json, identity=identity.did)

get_public_key

get_public_key(identity: str, passphrase: str | None = None) -> str

Retrieve the Ed25519 public key (hex) for an identity.

Parameters:

• identity (str) –

  The identity DID (did:keri:...).

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

  Override passphrase.

Returns:

• str –

  Hex-encoded Ed25519 public key.

Raises:

• CryptoError –

  If the identity key is not found.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

pub_key = auths.get_public_key(identity.did)

sign_as_agent

sign_as_agent(message: bytes, key_alias: str, passphrase: str | None = None) -> str

Sign bytes using a delegated agent's own key.

Unlike sign_as() which resolves by identity DID, this uses the agent's key alias directly — enabling delegated agents (did:key:) to sign.

Parameters:

• message (bytes) –

  Bytes to sign.

• key_alias (str) –

  The agent's key alias (e.g., "deploy-bot-agent").

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

  Override passphrase.

Returns:

• str –

  Hex-encoded Ed25519 signature.

Raises:

• CryptoError –

  If the agent key is not found or signing fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

agent = auths.identities.delegate_agent(identity.did, "bot", ["sign"])
sig = auths.sign_as_agent(b"hello", key_alias=agent._key_alias)

sign_action_as_agent

sign_action_as_agent(action_type: str, payload: str, key_alias: str, agent_did: str, passphrase: str | None = None) -> str

Sign an action envelope using a delegated agent's own key.

Parameters:

• action_type (str) –

  Action type string.

• payload (str) –

  JSON payload string.

• key_alias (str) –

  The agent's key alias.

• agent_did (str) –

  The agent's DID (included in the envelope).

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

  Override passphrase.

Returns:

• str –

  JSON-serialized signed action envelope.

Raises:

• CryptoError –

  If signing fails.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

agent = auths.identities.delegate_agent(identity.did, "bot", ["deploy"])
envelope = auths.sign_action_as_agent("deploy", payload, agent._key_alias, agent.did)

sign_commit

sign_commit(data: bytes, *, identity_did: str, passphrase: str | None = None) -> CommitSigningResult

Sign git commit/tag data, producing an SSHSIG PEM signature.

Uses a 3-tier fallback:

1. ssh-agent (fastest, works on dev machines with agent running)
2. auto-start agent (starts a transient agent process)
3. direct signing (works everywhere, including headless CI)

Parameters:

• data (bytes) –

  The raw commit or tag bytes to sign.

• identity_did (str) –

  The KERI DID of the identity to sign with.

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

  Optional passphrase (for headless envs without ssh-agent).

Returns:

• CommitSigningResult –

  CommitSigningResult with the SSHSIG PEM block, method, and namespace.

Raises:

• CryptoError –

  If signing fails or the identity key is not found.

• KeychainError –

  If the keychain is locked or inaccessible.

Examples:

result = auths.sign_commit(commit_bytes, identity_did=identity.did)

sign_artifact

sign_artifact(path: str, *, identity_did: str, expires_in: int | None = None, note: str | None = None, commit_sha: str | None = None) -> ArtifactSigningResult

Sign a file artifact, producing a dual-signed attestation.

Computes SHA-256 digest of the file and creates an attestation binding the digest to your identity.

Parameters:

• path (str) –

  Path to the file to sign.

• identity_did (str) –

  The identity DID to sign with (used as key alias).

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

  Duration in seconds until expiration (per RFC 6749).

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

  Optional human-readable note.

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

  Optional commit SHA to bind the attestation to.

Returns:

• ArtifactSigningResult –

  ArtifactSigningResult with the attestation JSON, RID, digest, and file size.

Raises:

• FileNotFoundError –

  If the file does not exist.

• CryptoError –

  If signing fails.

Examples:

result = auths.sign_artifact("release.tar.gz", identity_did=identity.did)

sign_artifact_bytes

sign_artifact_bytes(data: bytes, *, identity_did: str, expires_in: int | None = None, note: str | None = None, commit_sha: str | None = None) -> ArtifactSigningResult

Sign raw bytes, producing a dual-signed attestation.

Use this for non-file artifacts: container manifest digests, git tree hashes, API response bodies.

Parameters:

• data (bytes) –

  The raw bytes to sign.

• identity_did (str) –

  The identity DID to sign with (used as key alias).

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

  Duration in seconds until expiration (per RFC 6749).

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

  Optional human-readable note.

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

  Optional commit SHA to bind the attestation to.

Returns:

• ArtifactSigningResult –

  ArtifactSigningResult with the attestation JSON, RID, digest, and size.

Raises:

• CryptoError –

  If signing fails.

Examples:

result = auths.sign_artifact_bytes(manifest_bytes, identity_did=did)

publish_artifact

publish_artifact(attestation_json: str, *, registry_url: str, package_name: str | None = None) -> ArtifactPublishResult

Publish a signed attestation to a registry.

Parameters:

• attestation_json (str) –

  The attestation JSON string from sign_artifact().

• registry_url (str) –

  Base URL of the target registry.

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

  Optional ecosystem-prefixed identifier (e.g. "npm:react@18.3.0").

Returns:

• ArtifactPublishResult –

  ArtifactPublishResult with the registry RID, package name, and signer DID.

Raises:

• StorageError –

  If the attestation is a duplicate.

• VerificationError –

  If the registry rejects the attestation.

• NetworkError –

  If the registry is unreachable.

Examples:

signed = auths.sign_artifact("release.tar.gz", identity_did=did)
result = auths.publish_artifact(
    signed.attestation_json,
    registry_url="https://registry.example.com",
)

get_token

get_token(bridge_url: str, chain_json: str, root_key: str, capabilities: list[str] | None = None) -> str

Exchange an attestation chain for a bearer token.

Parameters:

• bridge_url (str) –

  The OIDC bridge base URL.

• chain_json (str) –

  JSON-serialized attestation chain.

• root_key (str) –

  Root identity's public key hex.

• capabilities (list[str] | None, default: None ) –

  Optional list of capabilities to request.

Returns:

• str –

  JWT bearer token string.

Raises:

• NetworkError –

  If the bridge is unreachable or returns an error.