> ## Documentation Index
> Fetch the complete documentation index at: https://keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Manage API keys and OAuth for your project.

Credentials let Keystroke actions safely call external services like Linear, Gmail, HubSpot, Slack, and more.

An **app** is the service you connect. A **credential** is one connected account or secret for that app. Actions declare the credentials they need, and Keystroke resolves the right organization, project, or user credential when the action runs.

Use credentials only for secrets and connected accounts. Keep non-secret configuration—such as spreadsheet IDs, channel names, and base URLs—in code or workflow input.

## Example requests

Ask your coding agent which service you want to use. It can wire up the app, credential, and actions that need it.

> "Connect our HubSpot account so our SDR agent can read and update deals."

> "Connect Slackbot so the team can message the data analyst agent in Slack, and schedule regular reports."

> "Read the Pylon documentation, create a custom API integration, and add actions that match the endpoints our support agent needs."

## Apps vs credentials

An **app** is a service Keystroke can connect to: Granola, Google Workspace, Slack, Salesforce, Snowflake, and the rest of the integration catalog.

A **credential** is one connected account for that app: an API key, OAuth connection, or managed connection instance. A single app can have several credentials, for example one organization-wide Hubspot connection and a project-level Hubspot connection with additional Hubspot permissions.

| Term                    | What it means                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **App**                 | A connectable external service shown in the Apps page and integration catalog       |
| **Credential**          | One connected account or secret for an app                                          |
| **Credential instance** | The stored credential record at an organization, project, or user scope             |
| **Gateway app**         | A messaging surface, like Slack, for messaging agents directly in third-party tools |
| **MCP server**          | A third-party MCP server registered as an org app (`apps create --mcp`)             |

<Note>
  "Integration" is synonymous with "app". An **app** is the user-facing thing you connect, and **credential** is the runtime binding your code consumes.
</Note>

## Connect apps and credentials

Keystroke supports several connection paths, depending on what you're building.

| Connection type           | Use it for                                                                          | How it works                                                                                                                                                                                |
| ------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Built-in OAuth apps**   | Apps like Google Workspace, GitHub, Gong, Snowflake, and other catalog integrations | Keystroke creates a managed app credential. In the hosted cloud, most of these run through Keystroke's platform MCP layer.                                                                  |
| **Built-in API key apps** | Apps that need a static secret, such as Exa                                         | Store an API key credential with the CLI or web app.                                                                                                                                        |
| **Gateway apps**          | External channels where people talk to agents, such as Slack                        | Connect the **Keystroke Slack App** (`connect slack --kind keystroke`; catalog slug `slackbot`), then bind a channel to an agent. See [external channels](/docs/learn/agents/external-channels). |
| **Custom apps**           | Your own APIs or internal services that need a secret                               | Register with `keystroke apps create` when Connect UI is needed, then `defineApp` + `app.action(...)` in code. See [custom apps and MCP](/docs/learn/credentials/custom-integrations).           |
| **Custom MCP servers**    | Connect to any third-party MCP server and enable agents to use its available tools  | `apps create --mcp`, connect, `apps actions list`, `apps execute` to smoke-test, sync, author `app.action`s, then `tools: [app]`.                                                           |

You can browse our [1,000+ built-in integrations](/docs/learn/credentials/built-in-integrations) in the app catalog, or jump to [custom apps and MCP](/docs/learn/credentials/custom-integrations) to learn more about connecting custom apps and MCP servers.

## Credential scopes

Every credential instance is available at one of three scopes:

| Scope            | Use it when                                                   |
| ---------------- | ------------------------------------------------------------- |
| **Organization** | The whole organization should share one connection or API key |
| **Project**      | A specific project(s) gets its own connection or secret       |
| **User**         | A specific person's connected account should be used          |

When building agents and workflows, Keystroke will automatically resolve credentials for each action (agent tools or workflow steps) in this order:

1. An explicit selection (a [credential assignment](/docs/learn/credentials/connect-credentials#bind-a-credential-to-a-step-tool-or-poll-action) on the step, tool, or poll consumer).
2. A pinned scope from `.scope("organization")`, `.scope("project")`, or `.scope("user")`.
3. The project default.
4. The organization default.
5. Throw a missing-credentials error.

User credentials are not part of the unpinned fallback chain. To use one: pin `.scope("user")` on the action, then assign that user's credential to the workflow step, agent tool, or poll consumer. See [using credentials in code](/docs/learn/credentials/use-credentials).

## Credentials on the platform

Credentials live in the platform: they're scoped to your organization, project, or user, and materialized on demand when a deployed project runs. Deploying does **not** upload `.env` or local secrets, so connect credentials against your cloud project with the web app or CLI.

```bash theme={null}
# Organization credential
keystroke credentials create exa --set apiKey=@env:EXA_API_KEY --scope org
```

See [connect and manage apps](/docs/learn/credentials/connect-credentials) for the full CLI and web workflow.

## How code consumes credentials

Credentials are declared on [actions](/docs/learn/actions/overview), not on agents or workflows directly. For a **new credentialed custom integration**, define the app once and create actions from it:

```ts theme={null}
import { defineApp } from "@keystrokehq/keystroke/app";
import { z } from "zod";

const acme = defineApp({
  slug: "my-org/acme",
  auth: "api_key",
  credential: { apiKey: z.string() },
});

export const lookupInvoice = acme.action({
  slug: "lookup-invoice",
  input: z.object({ id: z.string() }),
  output: z.object({ status: z.string() }),
  async run(input, credentials) {
    return callAcme(input.id, credentials["my-org/acme"].apiKey);
  },
});
```

`defineApp` binds the credential for you. Built-in catalog packages export actions the same way. See [custom apps and MCP](/docs/learn/credentials/custom-integrations) for catalog registration and the Connect flow, and [using credentials in code](/docs/learn/credentials/use-credentials) for scopes and resolution.

Agents and workflows consume credentials indirectly when they call that action as a tool or step.

## Platform API keys

App credentials are different from Keystroke platform API keys. Platform API keys authenticate your own systems to Keystroke's platform API and are managed under **Settings → API keys** or with `keystroke api-key`. App credentials authenticate Keystroke runs to third-party apps.

## LLM provider keys

App credentials are also different from LLM provider API keys. To run model inference on your own OpenAI, Anthropic, Google, Groq, or xAI keys (BYOK), connect them under **Settings → Managed services** or with `keystroke managed-services connect` — not through the apps catalog. See [Managed services](/docs/learn/settings/managed-services).

## Next steps

<CardGroup cols={2}>
  <Card title="Connect and manage apps" href="/docs/learn/credentials/connect-credentials">
    Use the web app and CLI to connect, scope, rotate, and revoke credentials.
  </Card>

  <Card title="Built-in integrations" href="/docs/learn/credentials/built-in-integrations">
    Use catalog apps and their generated actions.
  </Card>

  <Card title="Using credentials in code" href="/docs/learn/credentials/use-credentials">
    Declare credentials on actions and control resolution with scopes.
  </Card>

  <Card title="Custom apps and MCP" href="/docs/learn/credentials/custom-integrations">
    Register connectable apps and author them with `defineApp`.
  </Card>
</CardGroup>