> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# MEMO API 认证：Bearer JWT 与 X-API-Key

> 使用 Bearer JWT 或 X-API-Key 认证 MEMO API。所有业务接口按工作空间做 RBAC，角色分为 owner / admin / contributor / viewer。

MEMO API 用请求头认证。网关接受 `Authorization: Bearer <jwt>` 或 `X-API-Key: <sk_aria_...>`，两者等效。未携带任一凭证会返回 `401 Unauthorized`。

## 取得凭证

### 方案 A：账号 + JWT

注册或登录拿到 JWT：

```bash theme={null}
# 注册（首次）
curl -X POST https://memo.ariacompute.cn/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"<pwd>","display_name":"You"}'

# 登录，返回 token
curl -X POST https://memo.ariacompute.cn/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"<pwd>"}'
```

登录响应里的 `token` 用作后续请求的 Bearer：

```bash theme={null}
curl https://memo.ariacompute.cn/v1/workspaces \
  -H "Authorization: Bearer <jwt>"
```

### 方案 B：API Key

用 JWT 登录后，创建一个 API Key（仅展示一次）：

```bash theme={null}
curl -X POST https://memo.ariacompute.cn/v1/apikeys \
  -H "Authorization: Bearer <jwt>"
```

之后用 `X-API-Key` 头调用，无需再维护 JWT：

```bash theme={null}
curl https://memo.ariacompute.cn/v1/workspaces \
  -H "X-API-Key: <sk_aria_...>"
```

海外站点把主机换成 `https://memo.ariacompute.com`。

## 工作空间 RBAC

除 `/v1/auth/*` 与 `/v1/apikeys` 外，所有业务接口都挂在某个工作空间之下，并校验调用者在该空间的角色。角色由低到高：

| 角色 | 典型能力 |
| - | - |
| `viewer` | 读取知识库、记忆、Wiki 等 |
| `contributor` | 在 `viewer` 基础上可写入内容与记忆、运行 Agent |
| `admin` | 在 `contributor` 基础上可查看审计日志 |
| `owner` | 完全控制，含成员管理与删除 |

各接口在「认证」小节标注了所需的**最小角色**。角色不足返回 `403 Forbidden`。

## 错误响应

需要认证但凭证缺失或无效时，API 返回 `401`；角色不足返回 `403`。错误体统一为：

```json theme={null}
{
  "error": {
    "message": "Unauthorized",
    "type": "401 Unauthorized"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.