feat: derive agent identity from a single private-key env var

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[rishabhraj36]

Description

Agent identity is now fully derivable from a single environment variable, AUTHSOME_IDENTITY_PRIVATE_KEY. The DID is computed locally from the key, and the human-readable handle is resolved from the identity server by DID. This removes the need for AUTHSOME_IDENTITY, local identity files, or authsome init in headless/agent deployments.

Key changes:

• RuntimeIdentity.load() accepts a key-only env and defers the handle (the runtime handle is now optional and resolved later instead of raising ValueError).
• The CLI client resolves the handle from the server by DID before PoP signing. When the DID is unknown (brand-new agent), a handle is generated and registered via the existing claim flow.
• New reverse-lookup: GET /api/identities/by-did/{did} route + IdentityRegistry.resolve_by_did().
• AUTHSOME_IDENTITY is kept as an optional, deprecated handle override for backward compatibility.
• Docs updated with the single-key setup and a migration note.

Motivation and Context

The previous two-variable setup (AUTHSOME_IDENTITY + AUTHSOME_IDENTITY_PRIVATE_KEY) plus local filesystem bootstrap was unnecessarily convoluted for CI, containers, and ephemeral agents. This aligns with the cryptographic model: the identity is the key pair, and the handle is server-registered metadata that should be resolved from the identity server rather than supplied locally.

Closes#426.

How Has This Been Tested?

• Added unit tests following TDD (written first, watched fail, then implemented):
  • IdentityRegistry.resolve_by_did() returns the registered handle / None for unknown DIDs.
  • GET /api/identities/by-did/{did} returns the handle or 404.
  • RuntimeIdentity.load() with a key-only env derives the DID and leaves the handle unresolved.
  • Client resolves the handle from the server for a key-only env, with no filesystem identity artifacts.
  • Unknown DID auto-generates and registers a handle.
• Replaced the obsolete tests that asserted the old "private key requires AUTHSOME_IDENTITY" error.
• Full suite: 430 passed, 3 skipped. ruff and ty clean on all changed files.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• All new and existing tests passed.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agentr	🟢 Ready	View Preview	Jun 16, 2026, 8:04 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.