mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-11 03:37:56 +00:00
672defc08b
Rewrites 339 TypeScript calls across 50 pages from the rc.5 `method({ namespace, body })` form to the shipped `method(namespace, { ... })` form, and aligns field names with the live v5 spec: `attach` to `include`, `authUrl` to `authorization`, `lastSync` to `latestRun`, `deletedCount` to `count`, and the paginated `namespaces.list()`.
Renames container tags to namespaces across concepts, connectors, integrations and snippets. The namespace pages keep container tag in the description, search keywords and a rename note so old searches still land, and the v3 reference page points at v5.
The migration guide's SDK table now covers both 5.0.0 SDKs, and the SDK integration page uses the real client options (`baseUrl`, `timeoutInSeconds`, `maxRetries`) and error classes.
114 lines
No EOL
3.3 KiB
Text
114 lines
No EOL
3.3 KiB
Text
---
|
||
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). They can only access documents and search within that namespace — use them to give a client, session, or tenant limited access without shipping your org master key.
|
||
|
||
Pairs with [namespaces](/concepts/container-tags) for multi-tenant isolation.
|
||
|
||
**Allowed endpoints:** `/v3/documents`, `/v3/memories`, `/v4/memories`, `/v3/search`, `/v4/search`, `/v4/profile`
|
||
|
||
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 | — | The namespace to scope the key to. Alphanumeric, hyphens, underscores, colons, dots |
|
||
| `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",
|
||
"expiresAt": "2026-03-08T00:00:00.000Z",
|
||
"allowedEndpoints": ["/v3/documents", "/v3/memories", "/v4/memories", "/v3/search", "/v4/search", "/v4/profile"]
|
||
}
|
||
```
|
||
|
||
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 }
|
||
``` |