Skip to main content
POST/members

Add Member

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
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
One of: object
userId *string

The user to add (usr_...).

The user must already be an accepted member of the project's organization.

role *"PROJECT_ADMIN" | "PROJECT_EDITOR" | "PROJECT_MEMBER" | "PROJECT_VIEWER" | "PROJECT_AUDITOR" | "PROJECT_AUTHOR" | "PROJECT_ANALYST"

The project role to give: PROJECT_ADMIN, PROJECT_EDITOR, PROJECT_MEMBER, PROJECT_VIEWER, PROJECT_AUDITOR, PROJECT_AUTHOR or PROJECT_ANALYST.

idempotencyKeystring

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: object
email *string <email>

The email address of the user to add.

The user must already be an accepted member of the project's organization.

role *"PROJECT_ADMIN" | "PROJECT_EDITOR" | "PROJECT_MEMBER" | "PROJECT_VIEWER" | "PROJECT_AUDITOR" | "PROJECT_AUTHOR" | "PROJECT_ANALYST"

The project role to give: PROJECT_ADMIN, PROJECT_EDITOR, PROJECT_MEMBER, PROJECT_VIEWER, PROJECT_AUDITOR, PROJECT_AUTHOR or PROJECT_ANALYST.

idempotencyKeystring

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
HTTPK9O CodeDescription
201Created
401K9O_SESSION_EXPIREDYour session has expired; sign in again to continue.
403K9O_ACCESS_DENIEDYou do not have the required role (PROJECT_ADMIN or higher) to add members to this project.
410K9O_SLUG_GONEThe project slug in the URL has been renamed; update your integration to use the new slug.
Response body (201)
data *object

A project member.

userId *string

The member's user id (usr_...).

projectId *string

The project's id (proj_...).

role *"PROJECT_ADMIN" | "PROJECT_EDITOR" | "PROJECT_MEMBER" | "PROJECT_VIEWER" | "PROJECT_AUDITOR" | "PROJECT_AUTHOR" | "PROJECT_ANALYST"

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.

email *string

The member's sign-in email address.

displayName *string

The member's display name.

invitedAt *string <date-time>

When the membership was created.

acceptedAt *any

When the membership was accepted, or null while it is still an invitation.

One of: string <date-time>
or: null
state *"invited" | "active"

invited while acceptedAt is null, otherwise active.

meta *any

Request metadata: cost, timing and the request and trace ids.

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

Showing example in cURL

Request example
{
  "userId": "string",
  "role": "PROJECT_ADMIN",
  "idempotencyKey": "string"
}
Response example (201)
{
  "data": {
    "userId": "string",
    "projectId": "string",
    "role": "PROJECT_ADMIN",
    "email": "string",
    "displayName": "string",
    "invitedAt": "string",
    "acceptedAt": "string",
    "state": "invited"
  }
}

More in Members & End Users