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

# Overview

> Manage API keys and OAuth for your project.

Credentials let Luno OS 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 Luno OS 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 Luno OS 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 Integrations 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 (`integrations 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.

## Connect apps and credentials

Luno OS 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 | Luno OS creates a managed app credential. In the hosted cloud, most of these run through Luno OS'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 **Luno OS Slack App** (`connect slack --kind luno`; catalog slug `slackbot`), then bind a channel to an agent. See [external channels](https://docs.os.meetluno.ai/learn/agents/external-channels.md). |
| **Custom apps** | Your own APIs or internal services that need a secret | Register with `luno integrations create` when Connect UI is needed, then `defineIntegration` + `app.action(...)` in code. See [custom apps and MCP](https://docs.os.meetluno.ai/learn/credentials/custom-integrations.md). |
| **Custom MCP servers** | Connect to any third-party MCP server and enable agents to use its available tools | `integrations create --mcp`, connect, `integrations actions list`, `integrations execute` to smoke-test, sync, author `app.action`s, then `tools: [app]`. |

See [built-in integrations](https://docs.os.meetluno.ai/learn/credentials/built-in-integrations.md) for what ships today, or jump to [custom apps and MCP](https://docs.os.meetluno.ai/learn/credentials/custom-integrations.md) 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 |

Running a custom MCP tool follows the scope too: a user (personal) credential executes only for its owner (nobody else, org admins included), while organization and project credentials execute for anyone who can run agents and workflows in the project. See [who can execute a tool](https://docs.os.meetluno.ai/learn/credentials/custom-integrations.md#who-can-execute-a-tool).

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

1. An explicit selection (a [credential assignment](https://docs.os.meetluno.ai/learn/credentials/connect-credentials.md#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](https://docs.os.meetluno.ai/learn/credentials/use-credentials.md).

## 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
luno credentials create exa --set apiKey=@env:EXA_API_KEY --scope org
```

See [connect and manage apps](https://docs.os.meetluno.ai/learn/credentials/connect-credentials.md) for the full CLI and web workflow.

## How code consumes credentials

Credentials are declared on [actions](https://docs.os.meetluno.ai/learn/actions/overview.md), 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 { defineIntegration } from "@meetluno/luno/integration";
import { z } from "zod";

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

export const lookupInvoice = acme.action({
  slug: "lookup-invoice",
  name: "Look up invoice",
  description: "Fetch an Acme invoice's status",
  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);
  },
});
```

`defineIntegration` binds the credential for you. Built-in catalog packages export actions the same way. See [custom apps and MCP](https://docs.os.meetluno.ai/learn/credentials/custom-integrations.md) for catalog registration and the Connect flow, and [using credentials in code](https://docs.os.meetluno.ai/learn/credentials/use-credentials.md) 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 Luno OS platform API keys. Platform API keys authenticate your own systems to Luno OS's platform API and are managed under **Governance → API keys** or with `luno api-key`. App credentials authenticate Luno OS 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 **Governance → Managed services** or with `luno managed-services connect` — not through the apps catalog. See [Managed services](https://docs.os.meetluno.ai/learn/settings/managed-services.md).

## Next steps

> **[Connect and manage apps](https://docs.os.meetluno.ai/learn/credentials/connect-credentials.md)**
>
> Use the web app and CLI to connect, scope, rotate, and revoke credentials.

> **[Built-in integrations](https://docs.os.meetluno.ai/learn/credentials/built-in-integrations.md)**
>
> Use catalog apps and their generated actions.

> **[Using credentials in code](https://docs.os.meetluno.ai/learn/credentials/use-credentials.md)**
>
> Declare credentials on actions and control resolution with scopes.

> **[Custom apps and MCP](https://docs.os.meetluno.ai/learn/credentials/custom-integrations.md)**
>
> Register connectable apps and author them with `defineIntegration`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.