---
title: "Add User To Tenant"
method: POST
path: "/api/v1/tenants/users"
tags: ["tenants"]
---

# Add User To Tenant

`POST /api/v1/tenants/users`

## Request

- Base URL: `https://api.aws.cognee.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.aws.cognee.ai/api/v1/tenants/users`
- Auth: API key in header `X-Api-Key`

Add a user to a tenant.

This endpoint assigns a user to a specific tenant. Either user_id or email must be provided.
If email is provided, it will be resolved to a user_id before proceeding.

## Request Parameters
- **tenant_id** (UUID): The UUID of the tenant to assign the user to
- **user_id** (UUID, optional): The UUID of the user to add
- **email** (str, optional): The email of the user to add; converted to user_id if provided.
  If no account exists for the email, a stub user is created and added — they join
  automatically when they sign up with that email.

The new member is always emailed (COG-6177) — a sign-up CTA if they have no account
yet, a plain "you were added" notice if they do.

## Response
`200` — the member is in and the tenant pod knows them (`sync_status: "ok"`).
`207` — the member is in, but the tenant pod does not know them yet:
`sync_status` is `"unreachable"` (pod cold, suspended or restarting) or
`"rejected"` (the pod answered with an error). Nothing was mailed. **POST the
same member again** once the workspace is up — re-adding an existing member
re-runs the push and the notification (`already_member: true`); it is not a
conflict.

Body: `message`, `pending_invite` (an account had to be stubbed),
`invite_email_sent`, `sync_status`, `already_member`.

## Error Codes
- **400 Bad Request**: Neither user_id nor email provided
- **403 Forbidden**: Caller is neither the owner nor an admin of this tenant
- **404 Not Found**: User or tenant doesn't exist
- **503 Service Unavailable**: Caller is not the owner, and the workspace could not
  be reached to confirm they are an admin; nothing was written
- **500 Internal Server Error**: Error adding user to tenant

## Query parameters

- `tenant_id` string, uuid, required
- `user_id` string, uuid, nullable
- `email` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cognee/apis/cognee-api.md) - [All operations](https://skmtc.dev/cognee/apis/cognee-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cognee/apis/cognee-api/revisions/a7b6c6cb8212?raw)