# Notion

> Connect Notion to your agents for pages and databases.

**URL:** https://inference.sh/docs/credentials/notion
**Last updated:** 2026-09-24

---

Connect Notion to your agents for pages and databases.

---

## Overview

A Notion credential lets agents read and update pages and databases that you share during authorization.

### Why "Bring Your Own Key" (BYOK)?

Notion integrations are created in your workspace. BYOK keeps the OAuth client under your control.

**Benefits:**

- **Your workspace** — you choose which pages and databases to share at connect time
- **Scoped access** — read-only or read/write based on capability keys
- **Your integration** — the Notion integration appears in your workspace settings

---

## Prerequisites

Before connecting, you'll need:

1. A Notion account with access to the pages or databases you want agents to use
2. Permission to create integrations in your workspace

---

## Step 1: Create a Notion integration

1. Go to [Notion My Integrations](https://www.notion.so/my-integrations)
2. Click **New integration**
3. Name your integration (e.g., "Inference Agent")
4. Select the workspace
5. Under **Capabilities**, enable **Read content** and **Update content** as needed
6. Copy the **OAuth client ID** and **OAuth client secret**

---

## Step 2: Configure redirect URI

In your integration settings, set the redirect URI:

| Environment | Callback URL |
|-------------|-------------|
| Production | `https://app.inference.sh/settings/secrets/oauth/notion` |
| Staging | `https://app.staging.inference.sh/settings/secrets/oauth/notion` |
| Local dev | `http://localhost:3000/settings/secrets/oauth/notion` |

---

## Step 3: Connect in inference shell

### Configure credentials

1. Go to **vaults → credentials**
2. Find **Notion** and click **Configure**
3. Enter:
   - **Client ID** (`NOTION_CLIENT_ID`)
   - **Client Secret** (`NOTION_CLIENT_SECRET`)
4. Click **Save credentials**

### Authorize the connection

1. Click **Connect**
2. Select the pages and databases to share with the integration
3. Click **Allow access**
4. Done — the credential status shows **Connected**

Notion access is page-based: the pages you select during OAuth determine what agents can read or write. There are no separate OAuth scope strings.

---

## Capabilities

| Capability | Description |
|------------|-------------|
| `notion.read` | Read shared pages and databases |
| `notion.write` | Create and update shared pages and databases (includes read) |

---

## Using in apps

Declare Notion requirements in your app:

```yaml
# inf.yml
credentials:
  - key: notion.read
    description: Read project docs from Notion

  - key: notion.write
    description: Update status pages
    optional: true
```

At runtime, your app receives:

```bash
NOTION_ACCESS_TOKEN=oauth2-access-token
NOTION_WORKSPACE_ID=workspace-id
```

Use the token with the [Notion API](https://developers.notion.com/).

---

## Next

→ [Credentials overview](/docs/credentials/overview)  
→ [Using credentials in apps](/docs/extend/credentials)