supermemory/apps/docs/authentication.mdx

---
title: "API keys & auth"
description: "Org API keys, namespace-scoped keys, and connector branding."
sidebarTitle: "API keys"
icon: "/icons/hugeicons/key-01.svg"
---

## API keys

All API requests require authentication using a Bearer token. Get your API key from the [Developer Platform](https://console.supermemory.ai).

<Snippet file="getting-api-key.mdx" />

Include your key in all requests:

<CodeGroup>

```bash cURL
curl -X POST https://api.supermemory.ai/ns/user_123/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{"query": "hello"}'
```


```typescript TypeScript
import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: "YOUR_API_KEY" });
```


```python Python
from supermemory import Supermemory

client = Supermemory(api_key="YOUR_API_KEY")
```

</CodeGroup>

---

## Connector branding

When users connect external services (Google Drive, Notion, OneDrive), they see a "Log in to **Supermemory**" prompt by default. You can replace this with your own app name by providing your own OAuth credentials.

This works for Google Drive, Notion, and OneDrive. See the full setup in [Customization](/concepts/customization).

---

## Scoped API keys

Scoped keys are restricted to one namespace (what v3/v4 called a container tag), or to a fixed list of namespaces. They can read and write content only inside those namespaces, subject to the key's read/write permission and member restrictions — use them to give a client, session, or tenant limited access without shipping your org master key.

<Warning>
Namespace scoping is not read-only access. Writable scoped keys can update and delete documents and forget memories. Deleting or moving a namespace additionally requires an org admin or owner with write access to the source and, for moves, the destination.
</Warning>

Pairs with [namespaces](/concepts/container-tags) for multi-tenant isolation.

**Allowed endpoints:** `/ns/{namespace}/document`, `/ns/{namespace}/list`, `/ns/{namespace}/search`, `/ns/{namespace}/profile`, and `/ns/{namespace}/memories`; `/namespaces` and `/ns/{namespace}`; and the legacy `/v3/documents`, `/v3/memories`, `/v4/memories`, `/v4/conversations`, `/v3/search`, `/v4/search`, `/v4/profile`, `/v3/container-tags/list`, and `/v3/session` routes. Any other route returns `403`.

Scoped keys **cannot** read billing, manage org settings, or mint further keys.

### Create a scoped key

The scoped-key endpoint still takes the namespace in a field named `containerTag`.

```bash
curl https://api.supermemory.ai/v3/auth/scoped-key \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "containerTag": "my-project",
    "name": "my-key-name",
    "expiresInDays": 30
  }'
```

### Parameters

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `containerTag` | Yes, unless `containerTags` is set | — | The namespace to scope the key to. Up to 100 characters: letters, numbers, hyphens, underscores, colons |
| `containerTags` | No | — | Scope the key to several namespaces instead of one. Takes precedence over `containerTag` |
| `name` | No | `scoped_{containerTag}` | Display name for the key |
| `expiresInDays` | No | — | 1–365 days |
| `rateLimitMax` | No | `500` | Max requests per window (1–10,000) |
| `rateLimitTimeWindow` | No | `60000` | Window in milliseconds (1–3,600,000) |

### Response

```json
{
  "key": "sm_orgId_...",
  "id": "key-id",
  "name": "scoped_my-project",
  "containerTag": "my-project",
  "containerTags": ["my-project"],
  "expiresAt": "2026-03-08T00:00:00.000Z",
  "allowedEndpoints": ["/v3/session", "/v3/documents", "/v3/memories", "/v4/memories", "/v4/conversations", "/ns/*/memories", "/v3/search", "/v4/search", "/v4/profile", "/v3/container-tags/list", "/ns/*/document", "/ns/*/list", "/ns/*/search", "/ns/*/profile", "/namespaces$", "/ns$", "/ns/*$"]
}
```

Use the returned key like a normal API key — it just will not work outside its namespace.

### Disable a scoped key

Revoke with the `id` from creation. Subsequent requests get `401`. Memories and namespaces are **not** deleted.

```bash
curl https://api.supermemory.ai/v3/auth/scoped-key/KEY_ID \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

```json
{ "success": true }
```