---
title: "Invite new members"
method: POST
path: "/v2/members"
tags: ["Members"]
---

# Invite new members

`POST /v2/members`

Create an organization member if needed, and grant it permissions.

The member can be specified either by ID (for an existing member), or by email (for either an existing member or a new one).

For a new member, an invite will be sent.

## Query parameters

- `inviter_name` string
- `inviter_email` string

## Request body

- OrgMemberCreate
  - `id` string, uuid — Unique id of the account member
  - `email` string, email — Email of the user controlling this account
  - `permissions` Permission[], required
    - `organization_id` string, uuid, required
    - `project_id` string, uuid
    - `environment_id` string, uuid
    - `object_type` 'org' | 'project' | 'env', required — An enumeration.
    - `access_level` 'admin' | 'write' | 'read' | 'no_access', required — An enumeration.
    - `organization_key` string
    - `project_key` string
    - `environment_key` string
    - `organization_name` string
    - `project_name` string
    - `environment_name` string

## Response `200`

Successful Response

- OrgMemberReadWithGrants
  - `id` string, uuid, required — Unique id of the account member
  - `email` string, email, required — Email of the user controlling this account
  - `email_verified` boolean, required — Whether this email address is verified or not. For social providers like 'Login with Google' this is done automatically, otherwise we will send the user a verification link in email.
  - `name` string — Name of this user
  - `given_name` string — First name of the user
  - `family_name` string — Last name of the user
  - `picture` string — URL to picture, photo, or avatar of the user that controls this account.
  - `is_superuser` boolean, required — Whether or not this user has special access to permit.io organizations
  - `is_onboarding` boolean, required — Whether or not this user is currently onboarding, needs to be replaced by a user journey object
  - `onboarding_step` 'create_organization' | 'create_project' | 'create_resource' | 'create_actions' | 'assign_permissions' | 'assign_user_roles' | 'connect_sdk' | 'done', required — An enumeration.
  - `created_at` string, date-time, required — Date and time when the account member was created (ISO_8601 format).
  - `last_login` string, date-time — Last date and time this user logged in (ISO_8601 format).
  - `last_ip` string — Last IP address from which this user logged in.
  - `logins_count` integer — Total number of logins this user has performed.
  - `identities` IdentityRead[], required
    - `user_id` string, required — Unique User Id of this identity in the identity provider (including the provider type)
    - `provider` string, required — The identity provider type this identity came from
    - `sub` string, required — Unique User Id of this identity in the identity provider (NOT including the provider type)
    - `email` string, email, required — Email connected to this account identity
    - `email_verified` boolean, required — Whether this email address connected to this account identity is verified or not. For social providers like 'Login with Google' this is done automatically, otherwise we will send the user a verification link in email.
    - `auth0_info` object, required — Raw user info json coming from our identity provider and matching a specific account identity
  - `invite` InviteRead
    - `member_id` string, uuid — Unique id of the invite
    - `email` string, email, required — The invited member's email address
    - `role` 'admin' | 'write' | 'read' | 'no_access' — An enumeration.
    - `id` string, uuid, required — Unique id of the invite
    - `organization_id` string, uuid, required — Unique id of the organization that the invite belongs to.
    - `invite_code` string, uuid, required — The invite code that is sent to the member's email
    - `created_at` string, date-time, required — Date and time when the invite was created (ISO_8601 format).
    - `status` 'pending' | 'accepted' | 'failed' | 'canceled', required — An enumeration.
    - `failed_reason` string — if failed, the reason the invitation failed
  - `settings` object, required — Custom permit.io dashboard settings, such as preferred theme, etc.
  - `grants` Permission[], required
    - `organization_id` string, uuid, required
    - `project_id` string, uuid
    - `environment_id` string, uuid
    - `object_type` 'org' | 'project' | 'env', required — An enumeration.
    - `access_level` 'admin' | 'write' | 'read' | 'no_access', required — An enumeration.
    - `organization_key` string
    - `project_key` string
    - `environment_key` string
    - `organization_name` string
    - `project_name` string
    - `environment_name` string

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/permit/apis/permit-io-api.md) · [All operations](https://skmtc.net/permit/apis/permit-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/permit/permit-io-api/versions/f3391dcb29a4/schema)