Agent Identity API Reference

Identity, tracing, and attribution for agents — every public class, factory, and exception across promptise.identity.

For concepts and setup, start with the Agent Identity overview.

Public class

AgentIdentity

The entire user-facing surface. Construct a local identity directly, or use a credential factory (from_entra, from_aws, from_gcp, from_spiffe, from_oidc, or auto) to make it verifiable. Pass it to build_agent(identity=...) to attribute the agent's actions to it.

promptise.identity.AgentIdentity

The identity of an agent — for tracing and attributing its actions.

Construct a local identity directly, or use a credential factory (:meth:from_entra, :meth:from_aws, :meth:from_gcp, :meth:from_spiffe, :meth:from_oidc, or :meth:auto) to make it verifiable. An instance is immutable in identity and safe to share across threads.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Optional local handle. For a verifiable identity you can omit it: the authoritative identifier then comes from the IdP — the sub (or oid) claim of the credential — via :meth:subject and :meth:resolve_identifier. A local (unbacked) identity must supply one, since there is no IdP to ask.	None
name	str | None	Optional human-readable display name.	None
owner	str | None	Optional owner — the team or person operating the agent.	None
labels	Mapping[str, str] | None	Optional free-form key/value metadata (team, environment, version) carried alongside the identity on every trace.	None
credential	IdentityProvider | None	Optional :class:IdentityProvider that makes the identity verifiable. Prefer the factory classmethods; pass one directly only when wrapping a custom provider.	None

Raises:

Type	Description
ProviderConfigError	If neither an agent_id nor a credential is supplied — the identity would have no identifier and no IdP to derive one from.

agent_id = normalized instance-attribute

name = name instance-attribute

owner = owner instance-attribute

labels = dict(labels or {}) instance-attribute

is_verifiable property

True when a credential provider backs this identity.

credential_provider property

The backing provider's label (e.g. "entra-imds"), if any.

credential property

The backing :class:IdentityProvider (advanced use).

from_entra(agent_id=None, *, name=None, owner=None, labels=None, mode='auto', client_id=None, token_file=None, resource=_ENTRA_DEFAULT_RESOURCE) classmethod

Build an identity backed by Microsoft Entra ID.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None
mode	Literal['auto', 'imds', 'projected']	"auto" picks projected when $AZURE_FEDERATED_TOKEN_FILE is set, else IMDS.	'auto'
client_id	str | None	Managed-identity client id (IMDS mode).	None
token_file	str | Path | None	Projected token path (projected mode).	None
resource	str	Resource/audience the credential targets.	_DEFAULT_RESOURCE

from_aws(agent_id=None, *, name=None, owner=None, labels=None, mode='auto', region=None, token_file=None, audience=_AWS_DEFAULT_AUDIENCE, signing_algorithm=_AWS_DEFAULT_SIGNING_ALGORITHM) classmethod

Build an identity backed by AWS IAM.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None
mode	Literal['auto', 'sts', 'projected']	"auto" picks EKS-projected when $PROMPTISE_IDENTITY_TOKEN_FILE is set, else STS.	'auto'
region	str | None	AWS region for STS. Falls back to $AWS_REGION.	None
token_file	str | Path | None	EKS-projected token path.	None
audience	str	Audience the credential targets.	_DEFAULT_AUDIENCE
signing_algorithm	str	STS signing algorithm (e.g. "RS256").	_DEFAULT_SIGNING_ALGORITHM

from_gcp(agent_id=None, *, name=None, owner=None, labels=None, audience=_GCP_DEFAULT_AUDIENCE, service_account_email=_GCP_DEFAULT_SERVICE_ACCOUNT_EMAIL, request_timeout=5.0) classmethod

Build an identity backed by Google Cloud.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None
audience	str	Audience the credential targets.	_DEFAULT_AUDIENCE
service_account_email	str	Attached service account whose identity to request ("default" for the primary).	_DEFAULT_SERVICE_ACCOUNT_EMAIL
request_timeout	float	Seconds to wait for the metadata response.	5.0

from_spiffe(agent_id=None, *, name=None, owner=None, labels=None, mode='auto', token_file=None, socket_path=None, audience=_SPIFFE_DEFAULT_AUDIENCE) classmethod

Build an identity backed by SPIFFE / SPIRE.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None
mode	Literal['auto', 'file', 'sdk']	"auto" picks file mode when token_file is given, else SDK (Workload API) mode.	'auto'
token_file	str | Path | None	JWT-SVID path (file mode).	None
socket_path	str | None	Workload API socket (SDK mode). Falls back to $SPIFFE_ENDPOINT_SOCKET.	None
audience	str	Audience the JWT-SVID targets.	_DEFAULT_AUDIENCE

from_oidc(agent_id=None, *, issuer, name=None, owner=None, labels=None, token_file=None, token_fn=None, token_env_var=None) classmethod

Build an identity backed by a generic OIDC issuer.

Exactly one of token_file, token_fn, or token_env_var must be supplied.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
issuer	str	The OIDC issuer URL.	required
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None
token_file	str | Path | None	Path to a file holding the JWT.	None
token_fn	Callable[[], str] | None	Zero-arg callable returning the JWT.	None
token_env_var	str | None	Env var holding the JWT (re-read each refresh).	None

auto(agent_id=None, *, name=None, owner=None, labels=None) classmethod

Detect the platform and build a verifiable identity for it.

Uses environment markers to pick Entra, AWS, GCP, or SPIFFE and dispatches to the matching factory with platform defaults.

Parameters:

Name	Type	Description	Default
agent_id	str | None	Stable identifier for the agent.	None
name	str | None	Optional display name.	None
owner	str | None	Optional owning team or person.	None
labels	Mapping[str, str] | None	Optional free-form metadata.	None

Raises:

Type	Description
PlatformDetectionError	When no platform marker is present. Construct a local AgentIdentity(agent_id) or use an explicit factory instead.

subject()

Return the IdP-assigned identifier from the credential.

The persistent identity lives in the IdP; this reads who the IdP says the agent is — the sub claim (or oid for Microsoft Entra) of the verifiable credential. Acquiring the credential may contact the platform; the result is cached on the provider.

.. note:: The claim is read without verifying the credential's signature — the holder trusts its own IdP-issued token, and the receiving resource is what verifies the signature on presentation (see :class:~promptise.mcp.server.JwksAuth). For local attribution this is authoritative only insofar as the credential source is trusted; if you wire an untrusted token_fn / env var / file, the returned subject is only as trustworthy as that source.

Returns:

Type	Description
str	The IdP subject (sub) or, if absent, the object id
str	(oid).

Raises:

Type	Description
ProviderConfigError	If this is a local identity with no credential backing.
CredentialAcquisitionError	If the credential carries neither a sub nor an oid claim.

idp_claims()

Return the identity-relevant claims from the credential.

A subset of the credential's claims that describe who the IdP says the agent is and who issued the identity: sub, oid, iss, aud, azp, appid.

Raises:

Type	Description
ProviderConfigError	If this is a local identity.

resolve_identifier()

Return the authoritative identifier for this identity.

The explicit agent_id handle when one was given, otherwise the IdP subject (which contacts the platform). This is the value used to attribute the agent's actions.

claims()

Return the identity as a dict for stamping onto traces/audit.

Contains the agent_id and whichever of name, owner, credential_provider, and labels are set, plus a verifiable flag. Never includes a credential token.

get_credential(audience=None)

Return a signed credential (JWT) proving this identity.

Present this to a resource the agent calls — an MCP server or an HTTP API — so it can verify and attribute the caller.

Parameters:

Name	Type	Description	Default
audience	str | None	The resource the credential targets. When given, an IdP-backed identity whose provider can re-mint (Entra IMDS, AWS STS, GCP metadata, SPIFFE SDK) issues a credential scoped to that audience — so one identity can present to several resources. Projected-token and OIDC file/env modes have a fixed audience and ignore this. None uses the identity's configured default.	None

Returns:

Type	Description
str	The credential JWT.

Raises:

Type	Description
ProviderConfigError	When this is a local identity with no verifiable credential backing.
CredentialAcquisitionError	When the backing provider cannot mint a credential.

auth_header(audience=None)

Return {"Authorization": "Bearer <credential>"}.

Convenience for presenting the identity to an MCP server or API. Requires a verifiable identity (see :meth:get_credential).

Parameters:

Name	Type	Description	Default
audience	str | None	The resource the credential targets (see :meth:get_credential).	None

---

Credential providers

The verifiable backing of an identity. Use the factory classmethods on AgentIdentity; these classes are exported for advanced use.

IdentityProvider

promptise.identity.IdentityProvider

Bases: ABC

Abstract base for a verifiable agent-identity credential source.

A single instance is safe to share across threads. Concurrent calls to :meth:get_credential collapse into one acquisition, serialised by the lock. The cache is process-local: each process acquires its own credential rather than sharing one.

provider_name abstractmethod property

A short identifier used in log messages and error output.

get_credential(audience=None)

Return a currently-valid identity credential (a JWT).

Returns the cached credential for audience when it is still well inside its lifetime; otherwise acquires a fresh one. The credential's expiry is read from its exp claim; a credential with no decodable expiry (an opaque token, or a rotated file token) is re-acquired on every call.

Parameters:

Name	Type	Description	Default
audience	str | None	The resource the credential is for. None uses the provider's default audience. An active provider mints a separate credential per audience (cached per audience); a passive provider's token has a fixed audience and this is ignored.	None

Returns:

Type	Description
str	The credential JWT to present to a resource.

Raises:

Type	Description
CredentialAcquisitionError	When the platform cannot supply a fresh JWT and none is safely cached.

auth_header(audience=None)

Return a ready-to-use Authorization bearer header.

Convenience for presenting the identity credential to a resource — an MCP server or a third-party API the agent calls.

Parameters:

Name	Type	Description	Default
audience	str | None	The resource the credential is for (see :meth:get_credential).	None

Returns:

Type	Description
dict[str, str]	{"Authorization": "Bearer <credential>"}.

FileTokenProvider

promptise.identity.FileTokenProvider

Bases: IdentityProvider

Reads the identity JWT from a file on disk on every refresh.

Parameters:

Name	Type	Description	Default
token_file	str | Path	Filesystem path to the JWT file. The framework re-opens this file on every refresh; the projection mechanism (Kubernetes, AKS, spiffe-helper) keeps it up to date.	required
provider_label	str	Short string used in log messages and error output. Concrete provider subclasses (Entra projected, AWS EKS projected, SPIFFE file, generic OIDC file) pass their own label.	'file'

token_file property

Path of the projected JWT file (read-only access).

CallableTokenProvider

promptise.identity.CallableTokenProvider

Bases: IdentityProvider

Invokes a user-supplied callable to acquire the identity JWT.

Parameters:

Name	Type	Description	Default
token_fn	Callable[[str | None], str]	A callable that returns the JWT as a string, accepting the requested audience (str | None). Called fresh on every refresh — caching the result would defeat the platform's own rotation. Active providers honour the audience; passive ones ignore it.	required
provider_label	str	Short string used in log messages and error output. Concrete provider subclasses (Entra IMDS, AWS STS, GCP metadata, SPIFFE SDK, generic OIDC callable) pass their own label.	'callable'

Concrete providers

promptise.identity.EntraManagedIdentityProvider

Bases: CallableTokenProvider

Entra managed-identity credential source backed by Azure IMDS.

Parameters:

Name	Type	Description	Default
client_id	str | None	Optional client ID of a user-assigned managed identity. Omit for the resource's system-assigned identity.	None
resource	str	The resource (audience) to request — set this to the resource the agent presents its identity to.	_DEFAULT_RESOURCE
api_version	str	IMDS API version. Defaults to 2018-02-01.	_DEFAULT_IMDS_API_VERSION
imds_endpoint	str	Override for the IMDS URL — primarily for tests.	_IMDS_TOKEN_ENDPOINT
request_timeout	float	Seconds to wait for the IMDS response. Defaults to five seconds; IMDS is link-local and fast.	5.0

promptise.identity.EntraProjectedTokenProvider

Bases: FileTokenProvider

Entra projected-token credential source for AKS Workload Identity.

Parameters:

Name	Type	Description	Default
token_file	str | Path | None	Path to the projected token. Defaults to the value of $AZURE_FEDERATED_TOKEN_FILE or, if that is unset, :data:DEFAULT_AZURE_FEDERATED_TOKEN_FILE.	None

promptise.identity.AwsStsProvider

Bases: CallableTokenProvider

AWS STS web-identity-token credential source (lazily imports boto3).

STS is regional, so a region is required. It is resolved from the region argument, then AWS_REGION, then AWS_DEFAULT_REGION.

Parameters:

Name	Type	Description	Default
region	str | None	AWS region for the STS client. Falls back to AWS_REGION / AWS_DEFAULT_REGION.	None
audience	str	Audience to request in the web-identity token — the resource the agent authenticates to.	_DEFAULT_AUDIENCE
signing_algorithm	str	JWT signing algorithm STS should use. Defaults to RS256.	_DEFAULT_SIGNING_ALGORITHM

Raises:

Type	Description
ProviderConfigError	At construction, if no region can be resolved.

promptise.identity.AwsEksProjectedProvider

Bases: FileTokenProvider

AWS EKS projected-token credential source.

Reads a projected federated token from $PROMPTISE_IDENTITY_TOKEN_FILE (default /var/run/secrets/promptise/token). Requires no boto3.

Parameters:

Name	Type	Description	Default
token_file	str | Path | None	Projected-token path. Defaults to $PROMPTISE_IDENTITY_TOKEN_FILE or, if unset, :data:DEFAULT_PROMPTISE_IDENTITY_TOKEN_FILE.	None

promptise.identity.GcpMetadataProvider

Bases: CallableTokenProvider

GCP credential source backed by the Compute metadata server.

Parameters:

Name	Type	Description	Default
audience	str	Audience to request in the identity token — the resource the agent authenticates to.	_DEFAULT_AUDIENCE
service_account_email	str	The attached service account whose identity to request. "default" (the default) selects the instance's primary service account; pass a full email to select a specific one.	_DEFAULT_SERVICE_ACCOUNT_EMAIL
metadata_endpoint	str | None	Override for the metadata URL — primarily for tests. When None it is derived from service_account_email.	None
request_timeout	float	Seconds to wait for the metadata response. Defaults to five seconds; the metadata server is link-local.	5.0

promptise.identity.SpiffeFileProvider

Bases: FileTokenProvider

SPIFFE credential source reading a JWT-SVID from spiffe-helper.

Parameters:

Name	Type	Description	Default
token_file	str | Path	Path to the JWT-SVID file spiffe-helper rotates.	required

promptise.identity.SpiffeSdkProvider

Bases: CallableTokenProvider

SPIFFE credential source using the Workload API via pyspiffe.

Parameters:

Name	Type	Description	Default
socket_path	str | None	SPIRE agent Workload API socket. Falls back to $SPIFFE_ENDPOINT_SOCKET and then :data:DEFAULT_SPIFFE_ENDPOINT_SOCKET.	None
audience	str	Audience to request in the JWT-SVID — the resource the agent authenticates to.	_DEFAULT_AUDIENCE

promptise.identity.OidcFileProvider

Bases: FileTokenProvider

Generic OIDC credential source that reads the JWT from a file path.

A thin specialisation of :class:FileTokenProvider that records the issuer and fixes the provider label to "oidc:<issuer>". Construct via :meth:AgentIdentity.from_oidc rather than directly.

Parameters:

Name	Type	Description	Default
issuer	str	The OIDC issuer URL — the iss claim your JWTs carry. Recorded for diagnostics and embedded in the provider label.	required
token_file	str | Path	See :class:FileTokenProvider.	required

promptise.identity.OidcCallableProvider

Bases: CallableTokenProvider

Generic OIDC credential source that invokes a callable for the JWT.

A thin specialisation of :class:CallableTokenProvider that records the issuer and fixes the provider label to "oidc:<issuer>". Construct via :meth:AgentIdentity.from_oidc rather than directly. Environment-variable mode is implemented on top of this class with a callable that reads the variable fresh on every refresh.

Parameters:

Name	Type	Description	Default
issuer	str	The OIDC issuer URL — the iss claim your JWTs carry.	required
token_fn	Callable[[], str]	A zero-argument callable returning the JWT. The token's audience is fixed by the issuer, so a per-resource audience request is ignored (this is a passive provider).	required

---

Credential cache

CachedCredential

promptise.identity.CachedCredential dataclass

One cached identity credential (a verifiable JWT) and its expiry.

Immutable. A provider holds at most one instance and replaces it rather than mutating it.

Parameters:

Name	Type	Description	Default
token	str	The credential JWT the agent presents to resources.	required
expires_at_epoch	float | None	The Unix timestamp from the JWT's exp claim, or None when no expiry could be decoded (in which case the credential is always considered stale).	required

is_stale(buffer_seconds=CREDENTIAL_REFRESH_BUFFER_SECONDS)

Return True when the credential should be re-acquired.

A credential with no known expiry is always stale (re-acquired on every use). Otherwise it is stale once the current time is within buffer_seconds of the exp claim.

decode_jwt_claims

promptise.identity.decode_jwt_claims(jwt)

Best-effort decode of a JWT's claims payload, without verifying.

The holder of a credential does not verify its own signature — that is the receiving resource's job. This decodes the payload segment so the framework can read identity claims (sub, oid, …) and the expiry. Returns an empty dict if anything is malformed.

Parameters:

Name	Type	Description	Default
jwt	str	A compact-serialization JWT (header.payload.signature).	required

Returns:

Type	Description
dict[str, Any]	The decoded claims, or {} if the JWT cannot be parsed.

decode_jwt_expiry

promptise.identity.decode_jwt_expiry(jwt)

Best-effort read of the exp claim from a JWT, without verifying.

Parameters:

Name	Type	Description	Default
jwt	str	A compact-serialization JWT (header.payload.signature).	required

Returns:

Type	Description
float | None	The exp claim as a Unix timestamp, or None if absent or
float | None	malformed.

---

Exceptions

All derive from IdentityError.

promptise.identity.IdentityError

Bases: Exception

Base exception for every Agent Identity failure.

Catching :class:IdentityError catches every error raised by promptise.identity regardless of which provider produced it.

promptise.identity.CredentialAcquisitionError

Bases: IdentityError

A verifiable credential provider could not produce an identity JWT.

Most common causes:

• The platform metadata service (Azure IMDS, GCP metadata server, AWS STS) is unreachable from this workload.
• The federated token file declared by an environment variable does not exist or is not readable.
• A user-supplied callable raised an exception (the original exception is chained on __cause__).
• A required environment variable is unset.

promptise.identity.ProviderConfigError

Bases: IdentityError

A credential provider was misconfigured at construction time.

Most common causes:

• A required argument is missing and no environment fallback was set.
• Conflicting arguments were supplied (for example, both token_file and token_fn to the OIDC credential).
• A required optional dependency is missing — boto3 for AWS, or pyspiffe for SPIFFE SDK mode. The exception message names the exact pip install command that resolves it.

promptise.identity.PlatformDetectionError

Bases: IdentityError

:meth:AgentIdentity.auto could not detect a supported platform.

Most common cause: the process is running on a host that does not expose a workload identity (a developer laptop, a bare VM without managed identity, a container without service-account token projection). Either construct a local :class:AgentIdentity (just an agent_id) or use an explicit credential factory — from_entra, from_aws, from_gcp, from_spiffe, from_oidc — instead of AgentIdentity.auto().