Invite organization members¶

POST /api/v5/orgs/{org}/memberships/{username}

This endpoint invites the specified user to join the organization. You can set the member's permission (pull code, push code, administrator, or a custom role); if you do not specify one, push permission is granted by default. The endpoint returns the invited user's information and the set of permissions granted.

Access token support¶

AtomGit user access tokens

Anonymous access¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`org`	path	string	Yes	Address path of the namespace that owns the repository (address path of the enterprise, organization, or user)
`username`	path	string	Yes	User name (username/login)
`access_token`	query	string	Yes	User authorization code

Request Body:

When inviting a member, specify the member permission in the request body. If there is no request body, the default permission push is used.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permission": {
      "description": "Member permission: pull code (pull), push code (push), administrator (admin), customized (custom role). Default: push",
      "type": "string",
      "enum": ["pull", "push", "admin", "customized"],
      "default": "push"
    },
    "role_id": {
      "description": "Role ID. If permission is set to customized, the role ID must also be passed",
      "type": "string"
    }
  },
  "required": []
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`followers_url`	string	No	Yes	Followers list URL
`html_url`	string	No	Yes	User profile URL on the platform
`id`	string	No	Yes	User ID
`login`	string	No	Yes	Login name
`name`	string	No	Yes	User name
`type`	string	No	Yes	User type, such as `User`
`url`	string	No	Yes	User URL
`permissions`	object	No	Yes	Set of permissions granted after the invitation
`member_role`	string	No	Yes	Member role

permissions object

Field	Type	Always returned	Nullable	Description
`permissions.pull`	boolean	No	Yes	Whether the user has permission to pull code
`permissions.push`	boolean	No	Yes	Whether the user has permission to push code
`permissions.admin`	boolean	No	Yes	Whether the user has administrator permission
`permissions.customized`	boolean	No	Yes	Whether the user has custom role permission

Error responses¶

400 Parameter error

{
  "message": "The organization does not exist"
}

401 Unauthenticated

{
  "message": "Not logged in"
}

404 User does not exist

{
  "message": "User not found"
}

400 Invalid permission parameter

{
  "message": "permission must in [pull,push,admin,customized]"
}

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Parameter error (for example, the organization does not exist, the user has been blocked, or permission is invalid)
`401`	Requires authentication
`403`	Forbidden
`404`	The user does not exist
`500`	Internal system error

Request example¶

Parameter description¶

Replace <org> with the organization path (the address path of an enterprise, organization, or user); replace <username> with the user name to invite; replace <token> with your AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/orgs/<org>/memberships/<username>?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -d '{"permission": "push"}'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const url = new URL("https://api.atomgit.com/api/v5/orgs/<org>/memberships/<username>");
url.searchParams.set("access_token", "<YOUR-TOKEN>");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({ permission: "push" }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/orgs/<org>/memberships/<username>",
    params={"access_token": "<YOUR-TOKEN>"},
    json={"permission": "push"},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "followers_url": "https://api.atomgit.com/api/v5/users/xiaogang2/followers",
  "html_url": "https://api.atomgit.com/xiaogang2",
  "id": "65ffca965079ba0d1c00f6f2",
  "login": "xiaogang2",
  "name": "Xiao Gang 2",
  "type": "User",
  "url": "https://api.atomgit.com/api/v5/xiaogang2",
  "permissions": {
    "admin": false,
    "customized": true,
    "push": true,
    "pull": true
  },
  "member_role": ""
}

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`400`	Parameter error or the request cannot be parsed
`404`	The request path or the user does not exist
`405`	The request method is not supported
`429`	Too many requests; the rate limit was triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc