Skip to content

Call an AgentCore runtime with a Keycard token

Let other agents call an Amazon Bedrock AgentCore runtime with a Keycard token, and let Keycard policy decide which of them may.

An AgentCore runtime with a custom JWT authorizer can trust Keycard, so other agents call it with a Keycard token. Keycard issues that token only to the callers your Access Policies permit, and the runtime refuses everyone else.

  1. Calling agent Asks Keycard for a token for the Resource that stands for the runtime.
  2. Keycard Issues the token only if an Access Policy permits that caller. The token’s aud is the Resource’s identifier.
  3. AgentCore Runtime Checks the token against Keycard’s discovery document and keys, its aud, and its allowed clients.
  4. Your agent Receives the call.
  • A Keycard organization where you have the Admin Role.
  • An AgentCore runtime, and permission to change its authorizer.
  • The agent in that runtime registered as an Application, as in Run agents on Amazon Bedrock AgentCore.
  • The calling agent registered as an Application that can get Keycard tokens.

This recipe assumes your organization runs the managed default-zone-policies Policy Set. It includes default-user-grants, so any User who signs in to Keycard can also get a token for the runtime, and the recipe limits callers with the runtime’s allowed clients. See Access Policies.

  1. Add the Resource

    In Keycard Console, navigate to Resources → Add Resource → Add Manually (see Add a custom resource):

    Field Value
    Name A label for the runtime, for example <agent-name> runtime
    Identifier <runtime-resource-identifier>, a URN or another string that names this runtime. It becomes the aud of every token Keycard issues for the runtime.
    Credential Provider Zone Provider (badge Keycard STS)
    Provided by Application The Application of the agent that runs in the runtime

    Click Protect.

Add an Access Policy that lets each calling Application get a token for the runtime’s Resource:

@id("agentcore-runtime-callers")
permit (
principal is Keycard::Application,
action,
resource
) when {
principal.identifier == "<caller-app-identifier>" &&
resource.identifier == "<runtime-resource-identifier>"
};

Add the policy to a Policy Set of your own and activate the set. Keycard starts with the managed default-zone-policies, which you can’t edit, so create the set as Build a custom Policy Set describes, on schema 2026-06-18 if it should include any of the managed Policies. Until an active rule permits the caller, Keycard refuses its token request with access_denied.

Point the runtime’s authorizer at Keycard

Section titled “Point the runtime’s authorizer at Keycard”

Give the runtime a custom JWT authorizer with these values:

Setting Value
Discovery URL (discoveryUrl) <keycard-issuer-url>/.well-known/openid-configuration
Allowed audience (allowedAudience) ["<runtime-resource-identifier>"]
Allowed clients (allowedClients) ["<caller-client-id>"], one entry per credential a calling Application signs in with

Use your Keycard Issuer URL from Settings → Connection, with no trailing slash, as <keycard-issuer-url>. AgentCore requires the issuer in the discovery document to equal the token’s iss, and Keycard’s discovery document and tokens both carry that Issuer URL.

With allowed clients set, the runtime refuses a token from any caller not on the list, even when its aud is right. AgentCore compares each entry with the token’s client_id, which is the identifier of the credential the caller signed in with, not the Application’s identifier (see Token claims). For a Workload Identity credential, <caller-client-id> is the credential’s Subject, such as an Entra service principal’s object ID or a role’s ARN. For a client ID and secret, it’s the client ID. Update the list when you add or replace a caller’s credential.

With the AWS Terraform provider, the authorizer is a block on aws_bedrockagentcore_agent_runtime:

authorizer_configuration {
custom_jwt_authorizer {
discovery_url = "<keycard-issuer-url>/.well-known/openid-configuration"
allowed_audience = ["<runtime-resource-identifier>"]
allowed_clients = ["<caller-client-id>"]
}
}

The AgentCore control plane API, the AWS SDKs, and the AgentCore CLI take the same fields in the runtime’s customJWTAuthorizer configuration (see AWS’s Configure inbound JWT authorizer).

The calling agent requests its token the same way it requests any other, with resource set to <runtime-resource-identifier>. Then it calls the runtime over HTTPS with that token. The runtime ARN goes in the path URL-encoded, and the session ID must be at least 33 characters, so a UUID works:

Terminal window
RUNTIME_ARN="arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>"
ESCAPED_ARN=$(printf '%s' "$RUNTIME_ARN" | jq -sRr '@uri')
curl -sS -X POST \
"https://bedrock-agentcore.<region>.amazonaws.com/runtimes/$ESCAPED_ARN/invocations?qualifier=DEFAULT" \
-H "Authorization: Bearer <keycard-access-token>" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
-d '<payload>'

<keycard-access-token> is the access token from the calling Application’s token request, issued for the runtime’s Resource. <payload> is whatever your agent’s /invocations endpoint expects, such as {"prompt": "<prompt>"}. The AWS SDKs sign with SigV4, so call a JWT-authorized runtime with a plain HTTPS client like this one.

  1. Call the runtime without an Authorization header. AgentCore answers 401.
  2. Call it with a Keycard token for its Resource, as in Call the runtime with a Keycard token. AgentCore answers with your agent’s response.
  1. Remove the JWT authorizer from the runtime, or delete the runtime if you made it for this recipe.
  2. In Keycard Console, delete the runtime’s Resource and the agentcore-runtime-callers policy.
  • The runtime checks Keycard tokens itself, so a caller’s token keeps working until it expires, even after you take the caller’s access away.
  • While the active Policy Set includes the managed default-user-grants, any User who signs in to Keycard can get a token for the runtime. Use the authorizer’s allowed clients, or a set without default-user-grants, to limit it.
  • A runtime accepts either SigV4 or JWT bearer tokens, not both, so SigV4 callers need a second runtime.

access_denied: Application “…” is not allowed to access “…”

Section titled “access_denied: Application “…” is not allowed to access “…””

No active Access Policy lets the calling Application get a token for the runtime’s Resource. Add the permit above to your Policy Set and activate the set.

AgentCore answers 401 with “Missing Authentication Token”

Section titled “AgentCore answers 401 with “Missing Authentication Token””

The request had no bearer token. Send the Keycard access token in the Authorization header.

AgentCore answers 401 with “Claim ‘aud’ value mismatch with configuration.”

Section titled “AgentCore answers 401 with “Claim ‘aud’ value mismatch with configuration.””

The token was issued for a different Resource, such as a Gateway. Request the token with resource set to the runtime’s Resource identifier, and check that the same identifier is in the authorizer’s allowed audience.

AgentCore answers 401 with “Claim ‘client_id’ value mismatch with configuration.”

Section titled “AgentCore answers 401 with “Claim ‘client_id’ value mismatch with configuration.””

The caller’s credential isn’t in the authorizer’s allowed clients. Compare the client_id in the caller’s Keycard token with the list. For a Workload Identity credential it’s the credential’s subject, not the Application’s identifier.

Did this recipe work for you?