# Add Member

`POST /members` · Core · Members & End Users

Invites a new user or grants an existing org member a role on the project. The request body accepts `userId` or `email` plus a `role`. If the user is already an org member the operation is a direct role grant; if not, an invitation token is issued. Requires `PROJECT_ADMIN` or `ORG_ADMIN`.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| _one of_ | | |  |
| `userId` | string | yes | The user to add (`usr_...`). The user must already be an accepted member of the project's organization. |
| `role` | enum ("PROJECT_ADMIN", "PROJECT_EDITOR", "PROJECT_MEMBER", "PROJECT_VIEWER", "PROJECT_AUDITOR", "PROJECT_AUTHOR", "PROJECT_ANALYST") | yes | The project role to give: `PROJECT_ADMIN`, `PROJECT_EDITOR`, `PROJECT_MEMBER`, `PROJECT_VIEWER`, `PROJECT_AUDITOR`, `PROJECT_AUTHOR` or `PROJECT_ANALYST`. |
| `idempotencyKey` | string | no | A key that makes the request safe to retry: a repeat of a successful grant with the same key and body returns the same response instead of acting again. Generated when omitted. |
| _or_ | | |  |
| `email` | string (email) | yes | The email address of the user to add. The user must already be an accepted member of the project's organization. |
| `role` | enum ("PROJECT_ADMIN", "PROJECT_EDITOR", "PROJECT_MEMBER", "PROJECT_VIEWER", "PROJECT_AUDITOR", "PROJECT_AUTHOR", "PROJECT_ANALYST") | yes | The project role to give: `PROJECT_ADMIN`, `PROJECT_EDITOR`, `PROJECT_MEMBER`, `PROJECT_VIEWER`, `PROJECT_AUDITOR`, `PROJECT_AUTHOR` or `PROJECT_ANALYST`. |
| `idempotencyKey` | string | no | A key that makes the request safe to retry: a repeat of a successful grant with the same key and body returns the same response instead of acting again. Generated when omitted. |

## Responses

- **201**: Created

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | A project member. |
| `data.userId` | string | yes | The member's user id (`usr_...`). |
| `data.projectId` | string | yes | The project's id (`proj_...`). |
| `data.role` | enum ("PROJECT_ADMIN", "PROJECT_EDITOR", "PROJECT_MEMBER", "PROJECT_VIEWER", "PROJECT_AUDITOR", "PROJECT_AUTHOR", "PROJECT_ANALYST") | yes | The member's explicit project role. Org owners and admins also have admin access to every project without a row here, and are listed only if they have one. |
| `data.email` | string | yes | The member's sign-in email address. |
| `data.displayName` | string | yes | The member's display name. |
| `data.invitedAt` | string (date-time) | yes | When the membership was created. |
| `data.acceptedAt` | object | yes | When the membership was accepted, or null while it is still an invitation. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.state` | enum ("invited", "active") | yes | `invited` while `acceptedAt` is null, otherwise `active`. |
| `meta` | object | yes | Request metadata: cost, timing and the request and trace ids. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_SESSION_EXPIRED` | Your session has expired; sign in again to continue. |
| 403 | `K9O_ACCESS_DENIED` | You do not have the required role (PROJECT_ADMIN or higher) to add members to this project. |
| 410 | `K9O_SLUG_GONE` | The project slug in the URL has been renamed; update your integration to use the new slug. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/members' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/members', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/add-member
