Use credentials in code

Credentials are consumed by actions. Agents and workflows use credentials indirectly when they call those actions as tools or steps. This page covers the runtime model: how to declare credentials, how Keystroke resolves a credential instance, and how to pin scopes when a run should use a project, organization, or user connection.

Declare credentials on an action

For a new credentialed custom integration, prefer defineApp so the credential lives on the app and actions use app.action(...). This page shows the lower-level shape: a credential declaration listed on defineAction, which is what defineApp produces under the hood — and what you may still use for rare shared secrets that are not one service.

src/actions/search.ts

import { defineAction } from "@keystrokehq/keystroke/action";
import { defineCredential } from "@keystrokehq/keystroke/credentials";
import { z } from "zod";

const exa = defineCredential({
  key: "exa",
  fields: { apiKey: z.string() },
});

export const search = defineAction({
  slug: "search",
  input: z.object({ query: z.string() }),
  output: z.object({ results: z.array(z.string()) }),
  credentials: [exa] as const,
  async run(input, credentials) {
    return callSearchApi(input.query, credentials.exa.apiKey);
  },
});

The credential key (exa) is the app/credential slug Keystroke looks up in the vault. The schema validates the resolved secret before your action runs.

Credentials belong on actions (or on an app that binds them to actions), not on defineAgent() or defineWorkflow(). Agents and workflows get credentials by running actions that declare them. Actions with no secrets stay as plain defineAction — no app required.

Credential kinds

There are three runtime credential kinds:

Kind	Authoring shape	Use it for
`api_key`	`defineCredential({ key, fields })` or `credential.static()`	Static API keys and secret fields
`oauth_managed`	`defineCredential({ key, kind: "oauth" })` or `credential.oauth()`	Native OAuth connections, such as Slack gateway credentials
`keystroke`	`defineCredential({ key, kind: "keystroke" })` or generated app credentials	Hosted catalog apps routed through Keystroke’s platform MCP layer

Most custom API keys are authored via defineApp({ auth: "api_key", credential: … }). Built-in app packages usually define the credential for you. Standalone defineCredential is for edge cases — see custom apps and MCP.

Use actions in workflows and agents

Once an action declares credentials, use it like any other action.

// Workflow step
const results = await search.run({ query: "agentic workflows" });

// Agent tool
export default defineAgent({
  slug: "researcher",
  systemPrompt: "Use the search tool for current web research.",
  model: "xai/grok-4.5",
  tools: [search],
});

The runner resolves credentials immediately before the action executes. The model does not see the secret.

Resolution order

When an action runs, Keystroke resolves each credential requirement using the run context. Resolution order:

Explicit selection: a credential assignment (or other platform-supplied instance id) for this consumer wins.
Pinned scope: if the action or credential is scoped with .scope(...), only that scope is tried.
Project default: for unpinned credentials, try the default project credential.
Organization default: if no project credential resolves, try the default organization credential.
Error: if nothing resolves, the run fails with a missing-credentials error.

User credentials are intentionally not part of the unpinned chain. To use a user connection: pin .scope("user") on the action, then assign a user credential to that workflow step, agent tool, or poll consumer.

Pin a scope

Use .scope() when the action must use a specific credential scope.

// As an agent tool: require a user-scoped credential (then assign one via CLI/API)
tools: [slackSendMessage.scope("user")],

// As a workflow step: use the org credential
await slackSendMessage.run({ channel, markdown_text }).scope("organization");

You can pin a credential definition or an action. Pinning an action applies the scope to all credentials that action declares.

Scope	When to pin
`organization`	A shared org credential should always be used
`project`	The workflow should use a project-specific secret
`user`	The action should use someone’s personal connected account

Pinning .scope("user") alone does not pick a person or pull identity from the run. Associate a user credential with the step, tool, or poll consumer via an assignment (keystroke credentials assignments assign or the API). Without that assignment, the run cannot resolve the user credential. If a pinned scope has no matching credential (or assignment), Keystroke does not fall back to another scope.

Defaults and multiple credentials

Within a scope, Keystroke can resolve a credential automatically when:

There is exactly one credential instance for that app and scope.
Or there are multiple instances, but exactly one is marked as default.

If there are multiple possible credentials and no single default, the run needs an explicit selection. This is why labels and defaults matter when you manage credentials from the Apps page or CLI.

keystroke credentials update <credential-id> --label "Production Slack" --default

To make one specific step, agent tool, or poll action use a particular instance regardless of the default, bind it with an assignment.

Troubleshooting

When a credential can’t be resolved, the action fails before run executes, with a message that points at the fix:

Message	Cause	Fix
”This agent needs the `<key>` credential…”	Nothing resolved for that key at any tried scope	Connect the credential (`keystroke connect <key>` or the Apps page), check the action’s pinned scope, or assign a credential to the step/tool
”Multiple `<key>` credentials are available. Pick one…”	More than one instance and no default	Mark one default, or assign a specific instance

For .scope("user"), connect a user-scoped credential and assign it to the workflow step, agent tool, or poll consumer. User scope is not inferred from a run actor or actorId. The Slack gateway runs as the workspace’s connected account, not the individual who sent the message, so prefer organization or project scope there unless you have assigned a specific user credential.

Credential stores

Credentials live in the hosted platform credential store and are materialized to workers on demand. Deploying a project does not upload .env. If a deployed workflow uses an action with credentials, connect those credentials in the cloud first.

Next steps

Connect and manage apps

Create credential instances and choose their scopes.

Actions

Learn how actions define typed inputs, outputs, and credentials.

Workflow steps

Run credentialed actions as durable workflow steps.

Agent tools

Attach credentialed actions as tools an agent can call.

Get started

Learn

Build with AI

Resources

Use credentials in code

Declare credentials on an action

Credential kinds

Use actions in workflows and agents

Resolution order

Pin a scope

Defaults and multiple credentials

Troubleshooting

Credential stores

Next steps

Connect and manage apps

Actions

Workflow steps

Agent tools

​Declare credentials on an action

​Credential kinds

​Use actions in workflows and agents

​Resolution order

​Pin a scope

​Defaults and multiple credentials

​Troubleshooting

​Credential stores

​Next steps

Connect and manage apps

Actions

Workflow steps

Agent tools

Declare credentials on an action

Credential kinds

Use actions in workflows and agents

Resolution order

Pin a scope

Defaults and multiple credentials

Troubleshooting

Credential stores

Next steps