auth-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

## What this guide is for

This guide is for authentication against the **third-party service** your worker integrates with — the place data is coming from or going to (GitHub, Stripe, Salesforce, Google, Slack, etc.).

Use it when the worker needs credentials for a non-Notion API. Do not use it for Notion API tokens, `ntn login`, or general Notion workspace setup.

Never ask the user to send secret or environment-variable values in chat. For environment secrets, tell the user which variables are needed and have them enter the values directly in `.env` themselves. Do not open or print `.env` after they add them.

Most workers will use one of two auth patterns from the upstream service:

- personal API key / personal access token
- OAuth

For a personal API key / PAT, use a brokered credential unless worker code must read the plaintext value.

## Decision framework

Before recommending anything, check the provider's current developer docs. Confirm whether it offers:

- personal API keys / personal access tokens
- OAuth
- neither

Always research the provider's current auth docs on the web before advising the user. Do not rely on memory for auth availability, setup steps, or settings locations.

Then choose mechanically:

1. **Service offers personal API keys / PATs?** Recommend a brokered credential first when the credential is only used in outbound request headers to known domains. Otherwise, use the API key / PAT as an environment secret because worker code needs the plaintext value. It is usually the simplest fit for an individual-scoped worker.
2. **Service is OAuth-only?** Use OAuth.
3. **Both exist, but the worker should not depend on one person's credential or should be easy to re-auth if that person leaves?** Recommend OAuth.
4. **Service has neither?** See "When neither option is available" at the end of this guide.

State the recommendation in one sentence with the reason. Example: "Linear offers personal API keys, so use a brokered credential; it's the simplest fit and keeps the token out of the worker runtime."

## Setup: brokered credential

Pattern: declare where the credential may be injected with `worker.credential()`. The Workers service injects it into outbound request headers outside the worker runtime.

```ts
import { CREDENTIAL_VALUE } from "@notionhq/workers"

worker.credential("LINEAR_API_TOKEN", {
  network: [
    {
      domain: "api.linear.app",
      transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
    },
  ],
})
```

Do not read a brokered credential from `process.env` or add its header in `fetch`. Deploy the declaration, then have the user set its value themselves with `ntn workers env set LINEAR_API_TOKEN=<paste token>`. Use the narrowest exact domains that work.

## Setup: API key as an environment secret

Use this fallback only when worker code must read the plaintext value, such as for webhook verification, signing or encryption, a request body or query parameter, or a non-HTTP client.

Pattern: store the credential in `.env` (or directly in the deployed worker's secrets), read it from `process.env` inside the capability's `execute`, push `.env` to the deployed worker before going live.

1. Look up the provider's current docs for creating a token. Link the user to the exact settings page when possible.

2. **Have the user add the token to `.env` themselves** (create the file if it doesn't exist), or tell them the equivalent `ntn workers env set` command. Tell them the variable name to use:

   ```
   GITHUB_API_TOKEN=<paste your token here>
   ```

   `.env` is automatically loaded for local execution (`--local`).

3. Read the token inside `execute` (this is the part you write):

   ```ts
   const token = process.env.GITHUB_API_TOKEN ?? ""

   const res = await fetch("https://api.github.com/user", {
     headers: { Authorization: `Bearer ${token}` },
   })
   ```

4. If auth seems broken, test the token outside the worker first against a simple authenticated endpoint from the provider docs. Example for GitHub:

   ```shell
   curl -H "Authorization: Bearer $GITHUB_API_TOKEN" https://api.github.com/user
   ```

5. Test locally with `ntn workers exec <capability> --local`. Confirm auth works before deploying.

6. **Push the secret to the deployed worker.** Once the token is already in `.env`, run:

   ```shell
   ntn workers env push
   ```

   If the user prefers not to keep the token in `.env`, they can use the direct-set form instead:

   ```shell
   ntn workers env set GITHUB_API_TOKEN=<paste token>
   ```

7. Tell the user how to rotate: revoke the old token at the service, generate a new one, update `.env` (or `ntn workers env set` directly), and re-push if needed.

## Setup: OAuth

`worker.oauth()` declares an OAuth capability. The runtime handles the authorization redirect, token exchange, and refresh — you call `accessToken()` inside `execute` to get a fresh token.

The user has to register an OAuth app with the provider, then plug the credentials in:

```ts
const myAuth = worker.oauth("myAuth", {
  name: "my-provider",
  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
  tokenEndpoint: "https://provider.example.com/oauth/token",
  scope: "read write",
  clientId: process.env.MY_OAUTH_CLIENT_ID ?? "",
  clientSecret: process.env.MY_OAUTH_CLIENT_SECRET ?? "",
})
```

If the provider requires extra authorization parameters, add a concrete

From makenotion/notion-cookbook, MIT.

More from makenotion/notion-cookbook