A tenant user is one of your end-users. Every primitive — cards, inboxes, vault,
connections, verification, formation — is scoped to a tenant user, so each of your
customers gets their own isolated set of Naive resources. Tenant users are not auth
subjects: they never sign in, and you manage them entirely through the API/SDK/CLI.
On signup you automatically get a default tenant user, so solo usage needs no
users.create() — every top-level call (naive.cards, naive.vault, …) acts on it.
Multi-tenant builders create one tenant user per end-user and scope calls with
naive.forUser(id).
CLI First
# Create a tenant user and make them the active CLI subject
naive users create --external-id alice_db_uuid --email alice@example.com --label "Alice"
naive users list
naive use <user_id> # every subsequent command targets this user
| Tool | Type | Description |
|---|
users_list | Core | List all tenant users in the workspace |
users_create | Core | Provision a new tenant user |
users_get | Core | Fetch a single tenant user |
users_update | Core | Update label, email, metadata, or assigned Account Kit |
users_delete | Management | Remove a tenant user and their scoped resources |
Creating a User
Each user is governed by an Account Kit. Omit
account_kit_id to use your workspace’s Default kit.
curl -X POST https://api.usenaive.ai/v1/users \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{ "external_id": "alice_db_uuid", "email": "alice@example.com", "label": "Alice" }'
{
"id": "90a734a7-5f5a-4c4f-ba8f-80f770971d16",
"external_id": "alice_db_uuid",
"email": "alice@example.com",
"label": "Alice",
"status": "active",
"account_kit_id": "4273359a-7a80-460c-a93f-f49f9058fd23",
"is_default": false,
"created_at": "2026-06-04T06:45:36Z"
}
Parameters
| Param | Type | Required | Default | Description |
|---|
external_id | string | No | — | Your own stable id for this user (e.g. your DB row id) |
email | string | No | — | The end-user’s email |
label | string | No | — | Human-friendly display name |
account_kit_id | string | No | Default kit | The Account Kit governing this user |
metadata | object | No | — | Arbitrary JSON you can attach |
The default tenant user is created on signup and can’t be deleted. Reference it as the
sentinel default (e.g. /v1/users/default/vault) or via its id.
Listing & Fetching
curl https://api.usenaive.ai/v1/users \
-H "Authorization: Bearer nv_sk_your_key"
Updating & Deleting
# Reassign a user to a different Account Kit
curl -X PATCH https://api.usenaive.ai/v1/users/{user_id} \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{ "account_kit_id": "kit-uuid" }'
# Delete a user
curl -X DELETE https://api.usenaive.ai/v1/users/{user_id} \
-H "Authorization: Bearer nv_sk_your_key"
Error Handling
| Error | Cause | Recovery |
|---|
not_found | user_id doesn’t exist in this workspace (or a cross-tenant id) | Use GET /v1/users to list valid ids |
invalid_input | Malformed account_kit_id / user_id | Pass a valid UUID, or omit to use the Default kit |
duplicate_record | external_id already exists | Reuse the existing user or pick a new external_id |
Typical Workflow
Your app signs up a new customer "Alice"
│
├─ POST /v1/users → Provision her tenant user
│ { external_id: "alice_db_uuid" }
│ → id: 90a734a7-...
│
├─ POST /v1/users/90a734a7.../connections/connect → Connect Gmail for her
├─ PUT /v1/users/90a734a7.../vault/openai_key → Store her secret
└─ POST /v1/users/90a734a7.../cards → Issue her a card
(all isolated to Alice, governed by her Account Kit)
