Skip to content
forgit api docs

Get an organization role

GET
/orgs/{org}/organization-roles/{role_id}

Gets an organization role that is available to this organization. For more information on organization roles, see “Using organization roles.”

To use this endpoint, the authenticated user must be one of:

  • An administrator for the organization.
  • An organization member (or a member of a team) assigned a custom organization role that includes the View organization roles (read_organization_custom_org_role) permission. For more information, see “Permissions for organization access.”

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

role_id
required
integer

The unique identifier of the role.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
Organization Role

Organization roles

object
id
required

The unique identifier of the role.

integer format: int64
name
required

The name of the role.

string
description

A short description about who this role is for or what permissions it grants.

string
nullable
base_role

The system role from which this role inherits permissions.

string
nullable
Allowed values: read triage write maintain admin
source

Source answers the question, “where did this role come from?”

string
nullable
Allowed values: Organization Enterprise Predefined
permissions
required

A list of permissions included in this role.

Array<string>
organization
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
created_at
required

The date and time the role was created.

string format: date-time
updated_at
required

The date and time the role was last updated.

string format: date-time
Examples
Example default 
{
  "id": 8030,
  "name": "Custom Role Manager",
  "description": "Permissions to manage custom roles within an org",
  "permissions": [
    "write_organization_custom_repo_role",
    "write_organization_custom_org_role",
    "read_organization_custom_repo_role",
    "read_organization_custom_org_role"
  ],
  "organization": {
    "login": "github",
    "id": 1,
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "url": "https://api.github.com/orgs/github",
    "repos_url": "https://api.github.com/orgs/github/repos",
    "events_url": "https://api.github.com/orgs/github/events",
    "hooks_url": "https://api.github.com/orgs/github/hooks",
    "issues_url": "https://api.github.com/orgs/github/issues",
    "members_url": "https://api.github.com/orgs/github/members{/member}",
    "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "description": "A great organization"
  },
  "created_at": "2022-07-04T22:19:11Z",
  "updated_at": "2022-07-04T22:20:11Z"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}