Article version: GitHub.com

GitHub Enterprise administration

In this article

You can use these endpoints to administer your enterprise account.

Note: This article applies to GitHub Enterprise Cloud. To see the GitHub Enterprise Server version, use the Article version: drop-down menu.

Billing

Get GitHub Actions billing for an enterprise

Warning: The Billing API is currently in public beta and subject to change.

Gets the summary of the free and paid GitHub Actions minutes used.

Paid minutes only apply to workflows in private repositories that use GitHub-hosted runners. Minutes used is listed for each GitHub-hosted runner operating system. Any job re-runs are also included in the usage. The usage does not include the multiplier for macOS and Windows runners and is not rounded up to the nearest whole minute. For more information, see "Managing billing for GitHub Actions".

You must authenticate using an access token with the manage_billing:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/settings/billing/actions

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/actions
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/settings/billing/actions', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "total_minutes_used": 305,
  "total_paid_minutes_used": 0,
  "included_minutes": 3000,
  "minutes_used_breakdown": {
    "UBUNTU": 205,
    "MACOS": 10,
    "WINDOWS": 90
  }
}

Get GitHub Packages billing for an enterprise

Warning: The Billing API is currently in public beta and subject to change.

Gets the free and paid storage used for GitHub Packages in gigabytes.

Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."

You must authenticate using an access token with the manage_billing:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/settings/billing/packages

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/packages
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/settings/billing/packages', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "total_gigabytes_bandwidth_used": 50,
  "total_paid_gigabytes_bandwidth_used": 40,
  "included_gigabytes_bandwidth": 10
}

Get shared storage billing for an enterprise

Warning: The Billing API is currently in public beta and subject to change.

Gets the estimated paid and estimated total storage used for GitHub Actions and Github Packages.

Paid minutes only apply to packages stored for private repositories. For more information, see "Managing billing for GitHub Packages."

You must authenticate using an access token with the manage_billing:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/settings/billing/shared-storage

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/shared-storage
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/settings/billing/shared-storage', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "days_left_in_billing_cycle": 20,
  "estimated_paid_storage_for_month": 15,
  "estimated_storage_for_month": 40
}

GitHub Actions

List runner applications for an enterprise

Lists binaries for the runner application that you can download and run.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners/downloads

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners/downloads
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/downloads', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
[
  {
    "os": "osx",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-osx-x64-2.164.0.tar.gz",
    "filename": "actions-runner-osx-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-x64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-x64-2.164.0.tar.gz"
  },
  {
    "os": "linux",
    "architecture": "arm",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm-2.164.0.tar.gz"
  },
  {
    "os": "win",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-win-x64-2.164.0.zip",
    "filename": "actions-runner-win-x64-2.164.0.zip"
  },
  {
    "os": "linux",
    "architecture": "arm64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.164.0/actions-runner-linux-arm64-2.164.0.tar.gz",
    "filename": "actions-runner-linux-arm64-2.164.0.tar.gz"
  }
]

Create a registration token for an enterprise

Returns a token that you can pass to the config script. The token expires after one hour.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Example using registration token

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

./config.sh --url https://github.com/enterpises/octo-enterprise --token TOKEN
post /enterprises/{enterprise}/actions/runners/registration-token

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners/registration-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/registration-token', {
  enterprise: 'enterprise'
})

Default response

Status: 201 Created
{
  "token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-22T12:13:35.123-08:00"
}

Create a remove token for an enterprise

Returns a token that you can pass to the config script to remove a self-hosted runner from an enterprise. The token expires after one hour.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

Example using remove token

To remove your self-hosted runner from an enterprise, replace TOKEN with the remove token provided by this endpoint.

./config.sh remove --token TOKEN
post /enterprises/{enterprise}/actions/runners/remove-token

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners/remove-token
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runners/remove-token', {
  enterprise: 'enterprise'
})

Default response

Status: 201 Created
{
  "token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-29T12:13:35.123-08:00"
}

Get a self-hosted runner for an enterprise

Gets a specific self-hosted runner configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners/{runner_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id integer path

Unique identifier of the self-hosted runner.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_id: 42
})

Default response

Status: 200 OK
{
  "id": 23,
  "name": "mac_runner",
  "os": "macos",
  "status": "online",
  "busy": true
}

Delete a self-hosted runner from an enterprise

Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runners/{runner_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_id integer path

Unique identifier of the self-hosted runner.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_id: 42
})

Default Response

Status: 204 No Content

List self-hosted runners for an enterprise

Lists all self-hosted runners configured for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runners

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runners', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false
    }
  ]
}

List self-hosted runner groups for an enterprise

Lists all self-hosted runner groups for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "total_count": 3,
  "runner_groups": [
    {
      "id": 1,
      "name": "Default",
      "visibility": "all",
      "default": true,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/1/runners"
    },
    {
      "id": 2,
      "name": "octo-runner-group",
      "visibility": "selected",
      "default": false,
      "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/organizations",
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/runners"
    },
    {
      "id": 3,
      "name": "expensive-hardware",
      "visibility": "private",
      "default": false,
      "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/3/runners"
    }
  ]
}

Create a self-hosted runner group for an enterprise

Creates a new self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

post /enterprises/{enterprise}/actions/runner-groups

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

name string body

Required. Name of the runner group.

visibility string body

Visibility of a runner group. You can select all organizations or select individual organization. Can be one of: all or selected

Default: all
selected_organization_ids array of integers body

List of organization IDs that can access the runner group.

runners array of integers body

List of runner IDs to add to the runner group.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /enterprises/{enterprise}/actions/runner-groups', {
  enterprise: 'enterprise',
  name: 'name'
})

Default response

Status: 201 Created
{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners"
}

Get a self-hosted runner group for an enterprise

Gets a specific self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Default response

Status: 200 OK
{
  "id": 2,
  "name": "octo-runner-group",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners"
}

Update a self-hosted runner group for an enterprise

Updates the name and visibility of a self-hosted runner group in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

patch /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

name string body

Name of the runner group.

visibility string body

Visibility of a runner group. You can select all organizations or select individual organizations. Can be one of: all or selected

Default: all

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42 \
  -d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  name: 'name'
})

Default response

Status: 200 OK
{
  "id": 2,
  "name": "Expensive hardware runners",
  "visibility": "selected",
  "default": false,
  "selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners"
}

Delete a self-hosted runner group from an enterprise

Deletes a self-hosted runner group for an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Default Response

Status: 204 No Content

List self-hosted runners in a group for an enterprise

Lists the self-hosted runners that are in a specific enterprise group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/runners
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Default response

Status: 200 OK
{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false
    }
  ]
}

Set self-hosted runners in a group for an enterprise

Replaces the list of self-hosted runners that that are part of an enterprise runner group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runners array of integers body

Required. List of runner IDs to add to the runner group.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/runners \
  -d '{"runners":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runners: [
    42
  ]
})

Default Response

Status: 204 No Content

Add a self-hosted runner to a group for an enterprise

Warning: The self-hosted runner API for enterprise accounts is currently in public beta and subject to change.

Adds a self-hosted runner to a runner group configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runner_id integer path

Unique identifier of the self-hosted runner.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runner_id: 42
})

Default Response

Status: 204 No Content

Remove a self-hosted runner from a group for an enterprise

Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

runner_id integer path

Unique identifier of the self-hosted runner.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/runners/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  runner_id: 42
})

Default Response

Status: 204 No Content

List organization access to a self-hosted runner group in an enterprise

Lists the organizations with access to a self-hosted runner group.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

get /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

per_page integer query

Results per page (max 100)

page integer query

Page number of the results to fetch.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/organizations
JavaScript (@octokit/core.js)
await octokit.request('GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
  enterprise: 'enterprise',
  runner_group_id: 42
})

Default response

Status: 200 OK
{
  "total_count": 1,
  "organizations": [
    {
      "login": "octocat",
      "id": 161335,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "url": "https://api.github.com/orgs/octo-org",
      "repos_url": "https://api.github.com/orgs/octo-org/repos",
      "events_url": "https://api.github.com/orgs/octo-org/events",
      "hooks_url": "https://api.github.com/orgs/octo-org/hooks",
      "issues_url": "https://api.github.com/orgs/octo-org/issues",
      "members_url": "https://api.github.com/orgs/octo-org/members{/member}",
      "public_members_url": "https://api.github.com/orgs/octo-org/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    }
  ]
}

Set organization access for a self-hosted runner group in an enterprise

Replaces the list of organizations that have access to a self-hosted runner group configured in an enterprise.

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

selected_organization_ids array of integers body

Required. List of organization IDs that can access the runner group.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/organizations \
  -d '{"selected_organization_ids":[42]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  selected_organization_ids: [
    42
  ]
})

Default Response

Status: 204 No Content

Add organization access to a self-hosted runner group in an enterprise

Adds an organization to the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

put /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

org_id integer path

Unique identifier of an organization.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('PUT /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  org_id: 42
})

Default Response

Status: 204 No Content

Remove organization access to a self-hosted runner group in an enterprise

Removes an organization from the list of selected organizations that can access a self-hosted runner group. The runner group must have visibility set to selected. For more information, see "Create a self-hosted runner group for an enterprise."

You must authenticate using an access token with the admin:enterprise scope to use this endpoint.

delete /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

runner_group_id integer path

Unique identifier of the self-hosted runner group.

org_id integer path

Unique identifier of an organization.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/enterprises/ENTERPRISE/actions/runner-groups/42/organizations/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations/{org_id}', {
  enterprise: 'enterprise',
  runner_group_id: 42,
  org_id: 42
})

Default Response

Status: 204 No Content

SCIM

SCIM Provisioning for Enterprises

SCIM-enabled Identity Providers (IdPs) can use the SCIM API to automate the provisioning of enterprise membership. The GitHub API is based on version 2.0 of the SCIM standard.

The IdP must use https://api.github.com/scim/v2/enterprises/{enterprise}/ as the SCIM endpoint.

Note: The enterprise SCIM API is only available to enterprises on GitHub Enterprise Cloud with SAML SSO enabled. For more information about SCIM, see "About SCIM."

Authenticating calls to the SCIM API

You must authenticate as an owner of a GitHub enterprise to use its SCIM API. The API expects an OAuth 2.0 Bearer token to be included in the Authorization header. You may also use a personal access token, but you must first authorize it for use with your SAML SSO enterprise.

Mapping of SAML and SCIM data

The SAML IdP and the SCIM client must use matching NameID and userName values for each user. This allows a user authenticating through SAML to be linked to their provisioned SCIM identity.

SCIM groups are matched with GitHub organizations that have the exact same name, and are owned by the enterprise account.

The SAML IdP and SCIM client must be configured to exactly match the displayName of the SCIM group with the name of the corresponding GitHub organization. This allows GitHub to link the SCIM group with the GitHub organization membership.

Supported SCIM User attributes

NameTypeDescription
userNamestringThe username for the user.
name.givenNamestringThe first name of the user.
name.lastNamestringThe last name of the user.
emailsarrayList of user emails.
externalIdstringThis identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a GitHub user. You can find the externalID for a user either at the SAML provider, or using the List SCIM provisioned identities for an enterprise endpoint and filtering on other known attributes, such as a user's GitHub username or email address.
idstringIdentifier generated by the GitHub SCIM endpoint.
activebooleanUsed to indicate whether the identity is active (true) or should be deprovisioned (false).
groupsarrayOptional list of SCIM group IDs the user is a member of.

Note: Endpoint URLs for the SCIM API are case sensitive. For example, the first letter in the Users endpoint must be capitalized:

GET /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}

Supported SCIM Group attributes

NameTypeDescription
displayNamestringThe name of the SCIM group, which must exactly match the name of the corresponding GitHub organization. For example, if the URL of the organization is https://github.com/octo-org, the group name must be octo-org.
membersarrayList of SCIM user IDs that are members of the group.

List provisioned SCIM groups for an enterprise

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

get /scim/v2/enterprises/{enterprise}/Groups

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

startIndex integer query

Used for pagination: the index of the first result to return.

count integer query

Used for pagination: the number of results to return.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups
JavaScript (@octokit/core.js)
await octokit.request('GET /scim/v2/enterprises/{enterprise}/Groups', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "itemsPerPage": 2,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
      "externalId": null,
      "displayName": "octo-org",
      "members": [
        {
          "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
          "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
          "display": "octocat@github.com"
        },
        {
          "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
          "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
          "display": "hubot@example.com"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "created": "2020-06-09T03:10:17.000+10:00",
        "lastModified": "2020-06-09T03:10:17.000+10:00",
        "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "5e75bbbb-aa1a-11ea-8644-75ff655cdddd",
      "externalId": null,
      "displayName": "octo-docs-org",
      "members": [
        {
          "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
          "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
          "display": "octocat@github.com"
        }
      ],
      "meta": {
        "resourceType": "Group",
        "created": "2020-06-09T16:28:01.000+10:00",
        "lastModified": "2020-06-09T16:28:01.000+10:00",
        "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/5e75bbbb-aa1a-11ea-8644-75ff655cdddd"
      }
    }
  ]
}

Notes


Provision a SCIM enterprise group and invite users

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Provision an enterprise group, and invite users to the group. This sends invitation emails to the email address of the invited users to join the GitHub organization that the SCIM group corresponds to.

post /scim/v2/enterprises/{enterprise}/Groups

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

schemas array of strings body

Required. The SCIM schema URIs.

displayName string body

Required. The name of the SCIM group. This must match the GitHub organization that the group maps to.

members array of objects body

undefined

Properties of the members items

value (string)

Required. The SCIM user ID for a user.

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups \
  -d '{"schemas":["schemas"],"displayName":"displayName"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /scim/v2/enterprises/{enterprise}/Groups', {
  enterprise: 'enterprise',
  schemas: [
    'schemas'
  ],
  displayName: 'displayName'
})

Default response

Status: 201 Created
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": null,
  "displayName": "octo-org",
  "members": [
    {
      "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "display": "octocat@github.com"
    },
    {
      "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "display": "hubot@example.com"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2020-06-09T03:10:17.000+10:0",
    "lastModified": "2020-06-09T03:10:17.000+10:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
  }
}

Notes


Get SCIM provisioning information for an enterprise group

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

get /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_group_id string path

Identifier generated by the GitHub SCIM endpoint.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups/SCIM_GROUP_ID
JavaScript (@octokit/core.js)
await octokit.request('GET /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}', {
  enterprise: 'enterprise',
  scim_group_id: 'scim_group_id'
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": null,
  "displayName": "octo-org",
  "members": [
    {
      "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "display": "octocat@github.com"
    },
    {
      "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "display": "hubot@example.com"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2020-06-09T03:10:17.000+10:0",
    "lastModified": "2020-06-09T03:10:17.000+10:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
  }
}

Notes


Set SCIM information for a provisioned enterprise group

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Replaces an existing provisioned group’s information. You must provide all the information required for the group as if you were provisioning it for the first time. Any existing group information that you don't provide will be removed, including group membership. If you want to only update a specific attribute, use the Update an attribute for a SCIM enterprise group endpoint instead.

put /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_group_id string path

Identifier generated by the GitHub SCIM endpoint.

schemas array of strings body

Required. The SCIM schema URIs.

displayName string body

Required. The name of the SCIM group. This must match the GitHub organization that the group maps to.

members array of objects body

undefined

Properties of the members items

value (string)

Required. The SCIM user ID for a user.

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups/SCIM_GROUP_ID \
  -d '{"schemas":["schemas"],"displayName":"displayName"}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}', {
  enterprise: 'enterprise',
  scim_group_id: 'scim_group_id',
  schemas: [
    'schemas'
  ],
  displayName: 'displayName'
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": null,
  "displayName": "octo-org",
  "members": [
    {
      "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "display": "octocat@github.com"
    },
    {
      "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5",
      "display": "hubot@example.com"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2020-06-09T03:10:17.000+10:0",
    "lastModified": "2020-06-09T03:10:17.000+10:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
  }
}

Notes


Update an attribute for a SCIM enterprise group

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Allows you to change a provisioned group’s individual attributes. To change a group’s values, you must provide a specific Operations JSON format that contains at least one of the add, remove, or replace operations. For examples and more information on the SCIM operations format, see the SCIM specification.

patch /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_group_id string path

Identifier generated by the GitHub SCIM endpoint.

schemas array of strings body

Required. The SCIM schema URIs.

Operations array of objects body

Required. Array of SCIM operations.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups/SCIM_GROUP_ID \
  -d '{"schemas":["schemas"],"Operations":[{}]}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}', {
  enterprise: 'enterprise',
  scim_group_id: 'scim_group_id',
  schemas: [
    'schemas'
  ],
  Operations: [
    {}
  ]
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc",
  "externalId": null,
  "displayName": "octo-org",
  "members": [
    {
      "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "$ref": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "display": "octocat@github.com"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2020-06-09T03:10:17.000+10:00",
    "lastModified": "2020-06-09T03:10:17.000+10:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Groups/abcd27f8-a9aa-11ea-8221-f59b2be9cccc"
  }
}

Notes


Delete a SCIM group from an enterprise

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

delete /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_group_id string path

Identifier generated by the GitHub SCIM endpoint.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Groups/SCIM_GROUP_ID
JavaScript (@octokit/core.js)
await octokit.request('DELETE /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}', {
  enterprise: 'enterprise',
  scim_group_id: 'scim_group_id'
})

Default Response

Status: 204 No Content

Notes


List SCIM provisioned identities for an enterprise

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Retrieves a paginated list of all provisioned enterprise members, including pending invitations.

When a user with a SAML-provisioned external identity leaves (or is removed from) an enterprise, the account's metadata is immediately removed. However, the returned list of user accounts might not always match the organization or enterprise member list you see on GitHub. This can happen in certain cases where an external identity associated with an organization will not match an organization member:

  • When a user with a SCIM-provisioned external identity is removed from an enterprise, the account's metadata is preserved to allow the user to re-join the organization in the future.
  • When inviting a user to join an organization, you can expect to see their external identity in the results before they accept the invitation, or if the invitation is cancelled (or never accepted).
  • When a user is invited over SCIM, an external identity is created that matches with the invitee's email address. However, this identity is only linked to a user account when the user accepts the invitation by going through SAML SSO.

The returned list of external identities can include an entry for a null user. These are unlinked SAML identities that are created when a user goes through the following Single Sign-On (SSO) process but does not sign in to their GitHub account after completing SSO:

  1. The user is granted access by the IdP and is not a member of the GitHub enterprise.

  2. The user attempts to access the GitHub enterprise and initiates the SAML SSO process, and is not currently signed in to their GitHub account.

  3. After successfully authenticating with the SAML SSO IdP, the null external identity entry is created and the user is prompted to sign in to their GitHub account:

    • If the user signs in, their GitHub account is linked to this entry.
    • If the user does not sign in (or does not create a new account when prompted), they are not added to the GitHub enterprise, and the external identity null entry remains in place.
get /scim/v2/enterprises/{enterprise}/Users

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

startIndex integer query

Used for pagination: the index of the first result to return.

count integer query

Used for pagination: the number of results to return.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users
JavaScript (@octokit/core.js)
await octokit.request('GET /scim/v2/enterprises/{enterprise}/Users', {
  enterprise: 'enterprise'
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "itemsPerPage": 2,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
      "externalId": "00dowz5dr9oSfDFRA0h7",
      "userName": "octocat@github.com",
      "name": {
        "givenName": "Mona",
        "familyName": "Octocat"
      },
      "emails": [
        {
          "value": "octocat@github.com",
          "primary": true,
          "type": "work"
        }
      ],
      "groups": [
        {
          "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d"
        }
      ],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2020-05-30T04:02:34.000+10:00",
        "lastModified": "2020-05-30T04:05:04.000+10:00",
        "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "e18b8c34-a6b2-11ea-9d70-54abbd1c8fd5",
      "externalId": "sdfoiausdofiua",
      "userName": "hubot@example.com",
      "name": {
        "givenName": "hu",
        "familyName": "bot"
      },
      "emails": [
        {
          "value": "hubot@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "groups": [],
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2020-06-05T08:29:40.000+10:00",
        "lastModified": "2020-06-05T08:30:19.000+10:00",
        "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/e18b8c34-a6b2-11ea-9d70-54abbd1c8fd5"
      }
    }
  ]
}

Notes


Provision and invite a SCIM enterprise user

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Provision enterprise membership for a user, and send organization invitation emails to the email address.

You can optionally include the groups a user will be invited to join. If you do not provide a list of groups, the user is provisioned for the enterprise, but no organization invitation emails will be sent.

post /scim/v2/enterprises/{enterprise}/Users

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

schemas array of strings body

Required. The SCIM schema URIs.

userName string body

Required. The username for the user.

name object body

Required. undefined

Properties of the name object

givenName (string)

Required. The first name of the user.

familyName (string)

Required. The last name of the user.

emails array of objects body

Required. List of user emails.

Properties of the emails items

value (string)

Required. The email address.

type (string)

Required. The type of email address.

primary (boolean)

Required. Whether this email address is the primary address.

groups array of objects body

List of SCIM group IDs the user is a member of.

Properties of the groups items

value (string)

undefined

Code samples

Shell
curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users \
  -d '{"schemas":["schemas"],"userName":"userName","name":{"givenName":"givenName","familyName":"familyName"},"emails":["octocat@github.com"]}'
JavaScript (@octokit/core.js)
await octokit.request('POST /scim/v2/enterprises/{enterprise}/Users', {
  enterprise: 'enterprise',
  schemas: [
    'schemas'
  ],
  userName: 'userName',
  name: {
    givenName: 'givenName',
    familyName: 'familyName'
  },
  emails: [
    'octocat@github.com'
  ]
})

Default response

Status: 201 Created
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
  "externalId": "00dowz5dr9oSfDFRA0h7",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "type": "work",
      "primary": true
    }
  ],
  "groups": [
    {
      "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc"
  }
}

Notes


Get SCIM provisioning information for an enterprise user

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

get /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_user_id string path

Identifier generated by the GitHub SCIM endpoint.

Code samples

Shell
curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users/SCIM_USER_ID
JavaScript (@octokit/core.js)
await octokit.request('GET /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}', {
  enterprise: 'enterprise',
  scim_user_id: 'scim_user_id'
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
  "externalId": "00dowz5dr9oSfDFRA0h7",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "type": "work",
      "primary": true
    }
  ],
  "groups": [
    {
      "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc"
  }
}

Notes


Set SCIM information for a provisioned enterprise user

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Replaces an existing provisioned user's information. You must provide all the information required for the user as if you were provisioning them for the first time. Any existing user information that you don't provide will be removed. If you want to only update a specific attribute, use the Update an attribute for a SCIM user endpoint instead.

You must at least provide the required values for the user: userName, name, and emails.

Warning: Setting active: false removes the user from the enterprise, deletes the external identity, and deletes the associated {scim_user_id}.

put /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_user_id string path

Identifier generated by the GitHub SCIM endpoint.

schemas array of strings body

Required. The SCIM schema URIs.

userName string body

Required. The username for the user.

name object body

Required. undefined

Properties of the name object

givenName (string)

Required. The first name of the user.

familyName (string)

Required. The last name of the user.

emails array of objects body

Required. List of user emails.

Properties of the emails items

value (string)

Required. The email address.

type (string)

Required. The type of email address.

primary (boolean)

Required. Whether this email address is the primary address.

groups array of objects body

List of SCIM group IDs the user is a member of.

Properties of the groups items

value (string)

undefined

Code samples

Shell
curl \
  -X PUT \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users/SCIM_USER_ID \
  -d '{"schemas":["schemas"],"userName":"userName","name":{"givenName":"givenName","familyName":"familyName"},"emails":["octocat@github.com"]}'
JavaScript (@octokit/core.js)
await octokit.request('PUT /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}', {
  enterprise: 'enterprise',
  scim_user_id: 'scim_user_id',
  schemas: [
    'schemas'
  ],
  userName: 'userName',
  name: {
    givenName: 'givenName',
    familyName: 'familyName'
  },
  emails: [
    'octocat@github.com'
  ]
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
  "externalId": "00dowz5dr9oSfDFRA0h7",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "type": "work",
      "primary": true
    }
  ],
  "groups": [
    {
      "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc"
  }
}

Notes


Update an attribute for a SCIM enterprise user

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

Allows you to change a provisioned user's individual attributes. To change a user's values, you must provide a specific Operations JSON format that contains at least one of the add, remove, or replace operations. For examples and more information on the SCIM operations format, see the SCIM specification.

Note: Complicated SCIM path selectors that include filters are not supported. For example, a path selector defined as "path": "emails[type eq \"work\"]" will not work.

Warning: If you set active:false using the replace operation (as shown in the JSON example below), it removes the user from the enterprise, deletes the external identity, and deletes the associated :scim_user_id.

{
  "Operations":[{
    "op":"replace",
    "value":{
      "active":false
    }
  }]
}
patch /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_user_id string path

Identifier generated by the GitHub SCIM endpoint.

schemas array of strings body

Required. The SCIM schema URIs.

Operations array of objects body

Required. Array of SCIM operations.

Code samples

Shell
curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users/SCIM_USER_ID \
  -d '{"schemas":["schemas"],"Operations":[{}]}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}', {
  enterprise: 'enterprise',
  scim_user_id: 'scim_user_id',
  schemas: [
    'schemas'
  ],
  Operations: [
    {}
  ]
})

Default response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc",
  "externalId": "00dowz5dr9oSfDFRA0h7",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Monalisa",
    "familyName": "Octocat"
  },
  "emails": [
    {
      "value": "mona.octocat@okta.example.com",
      "type": "work",
      "primary": true
    },
    {
      "value": "monalisa@octocat.github.com",
      "type": "home"
    }
  ],
  "groups": [
    {
      "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d"
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00",
    "location": "https://api.github.com/scim/v2/enterprises/octo-corp/Users/92b58aaa-a1d6-11ea-8227-b9ce9e023ccc"
  }
}

Notes


Delete a SCIM user from an enterprise

Note: The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.

delete /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}

Parameters

Name Type In Description
accept string header

Setting to application/vnd.github.v3+json is recommended

enterprise string path

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

scim_user_id string path

Identifier generated by the GitHub SCIM endpoint.

Code samples

Shell
curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/scim/v2/enterprises/ENTERPRISE/Users/SCIM_USER_ID
JavaScript (@octokit/core.js)
await octokit.request('DELETE /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}', {
  enterprise: 'enterprise',
  scim_user_id: 'scim_user_id'
})

Default Response

Status: 204 No Content

Notes


Ask a human

Can't find what you're looking for?

Contact us