Credential Issuance

Keycard STS supports several methods for issuing credentials, each suited to different access scenarios. Every method produces a credential scoped to a specific resource. What varies is how the caller authenticates and whether access is on behalf of a user. The credential itself is determined by the resource’s credential type: a Keycard-issued token, a vaulted static credential, or brokered access from an external provider.

Every issuance is recorded in the audit log, evaluated against the zone’s access policies, and, when a user is involved, requires consent.

Used when an application needs to access resources on behalf of a user. The user authenticates interactively and the application receives credentials it can use to act for that user.

Keycard STS implements this using the authorization code flow with PKCE (OAuth 2.1). The application redirects the user to Keycard STS, the user authenticates via the zone’s identity provider, and the application exchanges the resulting authorization code for credentials. Confidential applications authenticate with their client credentials during the exchange; public applications (native apps, CLI tools, MCP clients) rely on PKCE alone.

During this flow, Keycard STS also handles:

• Consent — Keycard STS evaluates consent requirements for the application. If consent is required and has not been previously granted, the user sees a consent screen before the authorization code is issued.
• Brokered credentials — If the application has dependencies on external resources, the user authorizes the zone to broker credentials for each dependency, so that they are available for issuing later.

Keycard STS returns a credential, a refresh token, and (if the openid scope was requested) an ID token.

Used to obtain new credentials without requiring the user to interact again. Covers two cases: replacing an expired credential for the same resource, and obtaining a credential for a different resource using the existing authorization. If the target resource requires brokered credentials that have not been established, Keycard STS returns an error indicating user interaction is needed.

Used by an application to access resources on its own behalf, with no user involved. Covers service-to-service, machine-to-machine, and agent-to-agent communication.

The application authenticates directly to Keycard STS using the client credentials flow (OAuth 2.1) with any of the supported application credentials (client secret, workload identity, or URL credential). Public credentials are not supported for autonomous access because there is no user present to perform PKCE-protected authorization.

No user context is available. Because there is no user, client credentials cannot directly obtain brokered access to external resources. To access brokered resources on behalf of a user, an autonomous application can use impersonation.

Used when an application needs to access a downstream resource to fulfill a request on behalf of a user. For example, a user authorizes an MCP client, the MCP client calls an MCP server, and the MCP server needs to call an external API. Each hop in this chain requires its own credential, but the user only authenticates once.

The application at each hop presents the credential it received (the subject token) along with the target resource to Keycard STS using token exchange (RFC 8693). Keycard STS validates the subject token, evaluates policies to check that the application and subject are allowed to access the resource, and returns a new credential scoped to the requested resource. The new credential carries the full chain of delegation, so policy and audit logs can trace the path from the original user through every intermediary.

If the subject has not authorized access, Keycard STS returns an error code letting the application know that user interaction is required to establish credentials.

The application authenticates itself using any of the application credentials supported for autonomous access.

Used by an autonomous application to act as a specific user without the user being present. The application authenticates itself using autonomous access and names the user it acts for with a substitute-user token, then exchanges the two for a credential. It requires that the user has previously authorized the application through user delegation.

Using token exchange (RFC 8693), instead of a subject token from an active user, the application provides a substitute-user token containing the user’s identifier. Keycard STS resolves the identifier to the user and issues a credential as if that user had made the request.

Impersonation involves two independent authentication concerns. Keep them separate when designing an agent:

• The agent authenticates itself. The application presents one of its confidential application credentials (client secret, workload identity, or URL credential), exactly as in autonomous access. Public credentials are not supported — there is no user present to perform PKCE, and an unauthenticated caller must not be able to impersonate anyone.
• The agent names the user. Instead of a subject token from a live session, the application supplies a substitute-user token carrying the user’s identifier. This token is not a credential and proves nothing on its own.

All of the following must hold:

• Confidential client. The application authenticates with a client secret, workload identity, or URL credential. Public clients are rejected.
• Implicit consent. The application must be configured with consent set to implicit, because the user is not present to approve a consent screen during the exchange.
• Authorized by policy. The exchange is evaluated by normal access policy. Under the default policies an application may impersonate a user for any resource it declares as a dependency that the user has authorized; add a forbid policy to restrict it. The exchange is denied if the resource is not a dependency or a policy forbids impersonation.
• Prior authorization exists. The user must have authorized the application for the resource through user delegation (the interactive setup above), which establishes the consent grant and, for brokered resources, the brokered credentials. Otherwise the exchange returns interaction_required.

Keycard STS resolves the identifier to the user and issues a credential that acts as that user against the resource. What the credential contains depends on the resource: a Keycard-issued token carries the user as its subject (sub) with an act claim chain naming the application for audit; a brokered resource returns the provider’s own token for that user, which is often opaque and carries no such claims. Because no user is actually present there is no session, so the credential carries no session id — if your downstream authorization depends on session-derived context, account for its absence. Every impersonated issuance is recorded in the audit log with the application as the actor and the impersonated user as its delegator, so access is always traceable to both.

For a worked example using the SDK, see Act on Behalf of Absent Users.