Skip to content

Latest commit

 

History

History
107 lines (83 loc) · 3.7 KB

invitations.md

File metadata and controls

107 lines (83 loc) · 3.7 KB
Raw
stage group info
Growth
Expansion
To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Invitations API

Use the Invitations API to send email to users you want to join a group or project, and to list pending invitations.

Valid access levels

To send an invitation, you must have access to the project or group you are sending email for. Valid access levels are defined in the Gitlab::Access module. Currently, these levels are valid:

  • No access (0)
  • Guest (10)
  • Reporter (20)
  • Developer (30)
  • Maintainer (40)
  • Owner (50) - Only valid to set for groups

CAUTION: Caution: Due to an issue, projects in personal namespaces don't show owner (50) permission.

Invite by email to group or project

Invites a new user by email to join a group or project.

POST /groups/:id/invitations
POST /projects/:id/invitations
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project or group owned by the authenticated user
email integer/string yes The email of the new member or multiple emails separated by commas
access_level integer yes A valid access level
expires_at string no A date string in the format YEAR-MONTH-DAY 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "[email protected]&access_level=30" "https://gitlab.example.com/api/v4/groups/:id/invitations"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "[email protected]&access_level=30" "https://gitlab.example.com/api/v4/projects/:id/invitations"

Example responses:

When all emails were successfully sent:

{  "status":  "success"  }

When there was any error sending the email:

{
  "status": "error",
  "message": {
               "[email protected]": "Already invited",
               "[email protected]": "Member already exsists"
             }
}

List all invitations pending for a group or project

Gets a list of invited group or project members viewable by the authenticated user. Returns invitations to direct members only, and not through inherited ancestors' groups.

This function takes pagination parameters page and per_page to restrict the list of users.

GET /groups/:id/invitations
GET /projects/:id/invitations
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project or group owned by the authenticated user
page integer no Page to retrieve
per_page integer no Number of member invitations to return per page
query string no A query string to search for invited members by invite email. Query text must match email address exactly. When empty, returns all invitations. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/[email protected]"
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/:id/[email protected]"

Example response:

 [
   {
     "id": 1,
     "invite_email": "[email protected]",
     "invited_at": "2020-10-22T14:13:35Z",
     "access_level": 30,
     "expires_at": "2020-11-22T14:13:35Z",
     "user_name": "Raymond Smith",
     "created_by_name": "Administrator"
   },
]