Notion Worker Third-Party Auth Guide

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.

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):

   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:

   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:

   ntn workers env push

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

   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:

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 string-valued object, for example authorizationParams: { access_type: "offline" }.

Setup steps:

1. Check the provider's current OAuth docs. Confirm the authorization endpoint, token endpoint, scopes, any extra authorization params, and how the provider wants redirect URLs configured.

2. Register an OAuth app with the provider. If the provider asks for a redirect URL up front and you do not have it yet, create the app shell first and come back to fill in the redirect URL after the first deploy.

3. Have the user add credentials to .env themselves, or tell them the equivalent ntn workers env set commands. Tell them which variable names to use:

   MY_OAUTH_CLIENT_ID=<paste client id>
   MY_OAUTH_CLIENT_SECRET=<paste client secret>

4. Add the worker.oauth() declaration to src/index.ts. Read clientId/clientSecret from process.env.

5. Create the worker (if not already created), push secrets, and deploy. The deployed worker reads clientSecret from environment variables during capability registration, so the secret must be present remotely before deploy. Have the user run these themselves:

   ntn workers create --name <name>    # if not already created
   ntn workers env push                  # push .env to remote
   # or, to set values directly without putting them in .env:
   # ntn workers env set MY_OAUTH_CLIENT_SECRET=<paste secret>
   ntn workers deploy

   Important: any time the client ID or client secret changes, you must redeploy (ntn workers deploy) — the OAuth capability binds these values at registration time, so updating env vars alone won't take effect.

6. Get the redirect URL and have the user add it to the provider's app settings. The redirect URL comes from the deployed worker. Get it with:

   ntn workers oauth show-redirect-url

   The user must paste this exact value into their OAuth app's "redirect URI" (or "authorized redirect URL", or "callback URL") setting before starting the OAuth flow. Always remind the user of this step — OAuth will fail with a redirect mismatch error if it's missing or wrong.

7. Start the OAuth flow:

   ntn workers oauth start <oauthCapabilityKey>

   This opens the user's browser, walks them through the provider's consent screen, and stores the resulting tokens.

8. Use the token inside execute:

   const token = await myAuth.accessToken();
   const res = await fetch("https://provider.example.com/v1/things", {
     headers: { Authorization: `Bearer ${token}` },
   });

   accessToken() returns a valid, refreshed access token. The runtime handles refresh automatically — you don't need to track expiry yourself.