Authenticate deployed workloads

Your service authenticates to Keycard as an Application. Locally that means a client ID and secret. In production you want the same service to prove who it is without a long-lived secret in the host’s environment, because anything that can read that environment can act as your Application, from anywhere, until someone rotates the secret.

If your platform issues each running service a short-lived OIDC token, you don’t need the secret. Register the platform as a Provider, pin a Workload Identity credential on your Application to the token’s issuer and subject, and the SDK presents the platform’s token instead. The steps are the same on every platform that publishes an OpenID Connect discovery document for its tokens. Render and Fly.io have walkthroughs.

flowchart LR
    A[Your platform] -->|"Short-lived OIDC token"| B[Your service]
    B -->|"Token exchange + client assertion"| C[Keycard]
    C -->|"Match issuer + subject, verify signature"| C
    C -->|"Credential for the Resource"| B
    B -->|"Bearer token"| D[Resource]

1. The platform issues your service a short-lived token and rotates it. The token’s iss claim names the platform’s issuer; its sub claim names your exact service.
2. The SDK reads the token and presents it to Keycard as the Application’s client assertion on each token exchange.
3. Keycard looks up the Workload Identity credential registered for that issuer and subject, verifies the token’s signature against the issuer’s published keys, and authenticates the request as that Application.
4. Token exchange proceeds as it does locally: your service receives credentials for the Resources it depends on.

Because the credential is pinned to the subject, another service on the same platform presents a different sub and does not match.

• A service that authenticates to Keycard with a client secret today, and its Application in Keycard Console. Protect MCP servers and APIs or Access APIs on Behalf of Users get you there.
• A platform that issues OIDC tokens to running services, such as Render or Fly.io.
• Manager access to the Zone (see Roles & Permissions).

Keycard matches the token’s iss and sub claims exactly. Each platform builds them from IDs its dashboard or CLI shows, so you can register the credential before you deploy:

Create a separate Application for the deployment rather than adding the credential to your local one. Each environment then has its own identity, its own dependencies and its own audit trail, and removing one’s credential never touches the other.

1. Register the platform as a Provider

   In Keycard Console, navigate to Providers → Add Provider:

   Field	Value
   Name	A label, for example Render OIDC
   Issuer URL	The issuer from the table above

   Leave Client ID and Client Secret empty. Keycard discovers the issuer’s signing keys from its OpenID Connect discovery document.

2. Create the production Application

   Navigate to Applications → Add Application and name it. On its details page, give it what the deployed service provides and depends on, mirroring your local Application:

   • On the Provides tab, add the Resource for the deployed server’s public URL. Register that Resource first under Resources → Add Resource → Add Manually, with Zone Provider as its credential provider.
   • On the Dependencies tab, add the same external Resources your local Application depends on.

   Don’t generate a client ID and secret for this Application.

3. Add a Workload Identity credential

   On the Application’s Application Credentials tab, click Add credential and choose Workload Identity:

   Field	Value
   Provider	The Provider from step 1
   Subject	The subject from the table above

   The subject must match the token’s sub claim character for character. Console marks the field optional; set it anyway, because a credential with no subject matches no token. A trailing * matches every subject that starts with the text before it, so workspace:<workspace-id>:* trusts every service in a Render workspace at the cost of looser pinning. When several credentials match one token, an exact subject wins over a wildcard and a longer prefix wins over a shorter one.

One codebase runs locally with a client secret and in production with the platform’s token. How the SDK picks the credential differs by language.

import os

from keycardai.fastmcp import AuthProvider

# No application_credential argument: the SDK selects it from the environment.
auth_provider = AuthProvider(
    zone_url=os.environ["KEYCARD_ISSUER"],
    mcp_server_url=os.environ["MCP_SERVER_URL"],
)

import { AuthProvider } from "@keycardai/mcp/server/auth/provider";
import { ClientSecret } from "@keycardai/mcp/server/auth/credentials";
import { WorkloadIdentity, FileTokenSource } from "@keycardai/oauth/server";

const { KEYCARD_CLIENT_ID, KEYCARD_CLIENT_SECRET } = process.env;

const authProvider = new AuthProvider({
  zoneUrl: process.env.KEYCARD_ISSUER!,
  applicationCredential:
    KEYCARD_CLIENT_ID && KEYCARD_CLIENT_SECRET
      ? new ClientSecret(KEYCARD_CLIENT_ID, KEYCARD_CLIENT_SECRET) // local
      : new WorkloadIdentity(new FileTokenSource()), // deployed
});

zone_url / zoneUrl is your Zone’s Issuer URL, shown in Keycard Console under Settings → Connection. Both SDKs fetch the token on every token exchange, so the platform’s rotation needs no handling in your code.

Deploy, connect a client, and call a tool that reaches an external API. Then open the production Application in Keycard Console and select its Activity tab: each credential the deployed service was issued is listed there. If the call fails instead, see Troubleshooting.

No Workload Identity credential matches the token. The message includes the issuer and subject exactly as Keycard read them from the token; compare them with the Provider’s Issuer URL and the credential’s Subject in Console. Usual causes: a subject that names a different environment or service ID, a Provider whose Issuer URL differs from iss by a character, or a credential with no subject.

The Python SDK found a client secret and a token file (or key directory) at once and won’t guess. Remove KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET from the service, or set KEYCARD_APPLICATION_CREDENTIAL_TYPE=workload_identity, and redeploy.

KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET are set on the service and your code prefers them, as the TypeScript example above does and as keycardai-fastmcp before 0.7 did. Remove them and redeploy.

The production Application is missing that Resource under Dependencies. Dependencies belong to the Application, so the local one’s don’t carry over.

• Give an agent its own access: an agent that acts as itself, calling an API directly or through a Gateway.
• Give an agent its own identity: the case for workload identity, and what to tell a reviewer about the subject pin.
• Audit Log & Sessions: watch every credential the production Application is issued.
• Applications and Providers: the identity and credential model behind these steps.