Get organization custom roles¶

GET /api/v5/orgs/{org}/customized_roles

This endpoint returns the list of custom roles of the specified organization, including the ID, name, access level, and member count of each role, so that you can review the organization's custom role configuration.

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	Organization path (path/login)
`access_token`	query	string	Yes	User authorization code

Response parameters¶

The endpoint returns an array of custom role objects. Each element represents one custom role in the organization.

Field	Type	Always returned	Nullable	Description
`id`	string	Yes	No	Role ID
`name`	string	Yes	No	Role name
`name_cn`	string	Yes	No	Role name in Chinese
`product_id`	string	Yes	No	Product ID
`access_level`	integer	Yes	No	Access level
`created_at`	string	Yes	No	Creation time
`role_type`	string	Yes	No	Role type (the custom roles returned by this endpoint are `project-customized`)
`updated_at`	string	Yes	No	Update time
`description`	string	Yes	No	Role description
`member_count`	integer	Yes	No	Number of members
`role_from`	string	Yes	No	Role source
`mgnt_mode`	integer	Yes	No	Management mode

Error responses¶

When authentication fails, a parameter is invalid, or you do not have access, the endpoint returns a unified error response body with the fields error_code / error_code_name / error_message / trace_id (trace_id may be omitted).

400 Parameter error

{
  "error_code": 400,
  "error_code_name": "BAD_REQUEST",
  "error_message": "org not found",
  "trace_id": "..."
}

401 Unauthenticated

{
  "error_code": 401,
  "error_code_name": "UNAUTHORIZED",
  "error_message": "Missing or invalid access token",
  "trace_id": "..."
}

403 Forbidden

{
  "error_code": 403,
  "error_code_name": "FORBIDDEN",
  "error_message": "Access denied",
  "trace_id": "..."
}

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Parameter error
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`429`	Too many requests; the rate limit was triggered
`500`	Internal system error

Request example¶

Parameter description¶

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

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/orgs/<org>/customized_roles?access_token=<token>'   -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const token = "<YOUR-TOKEN>";
const org = "<org>";
const response = await fetch(`https://api.atomgit.com/api/v5/orgs/${org}/customized_roles?access_token=${token}`, {
  headers: {
    "Accept": "application/json",
  },
});

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

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

Python¶

import requests

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

print(resp.json())

Response example¶

Status code: 200

[
  {
    "id": "123456",
    "name": "admin-custom",
    "name_cn": "Custom administrator role",
    "product_id": "gitcode",
    "access_level": 60,
    "created_at": "2024-01-01 00:00:00",
    "role_type": "project-customized",
    "updated_at": "2024-01-02 00:00:00",
    "description": "Custom administrator role of the organization",
    "member_count": 3,
    "role_from": "custom",
    "mgnt_mode": 1
  }
]

Error codes¶

Error code	Description
`400`	Parameter error or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`403`	Forbidden; you do not have permission to view the custom roles of this organization
`404`	The request path 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