openapi: 3.0.3
info:
version: 1.1.4
title: GitHub SCIM API
description: >-
The GitHub SCIM (System for Cross-domain Identity Management) API enables
automated user provisioning and deprovisioning for GitHub Enterprise Cloud
organizations through identity providers like Azure AD, Okta, or OneLogin.
This API allows IT administrators to programmatically manage user
identities, group memberships, and access permissions by synchronizing user
data from their organization's identity management system directly to
GitHub. With SCIM, you can automatically create new users when employees
join, update user information when it changes in your identity provider,
remove access when employees leave, and manage team memberships based on
directory groups—streamlining user lifecycle management and ensuring
consistent access control across your organization's GitHub resources.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Attribute
- name: Delete
- name: Enterprise
- name: Get
- name: Groups
- name: Identities
- name: Information
- name: Lists
- name: Provision
- name: Provisioned
- name: Provisioning
- name: Scim
- name: Sets
- name: Update
- name: Users
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: HOSTNAME
protocol:
description: Self-hosted Enterprise Server protocol
default: http
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/scim/v2/Groups:
get:
summary: GitHub List Provisioned Scim Groups for an Enterprise
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Lists provisioned SCIM groups in an enterprise.
You can improve query search time by using the `excludedAttributes`
query parameter with a value of `members` to exclude members from the
response.
operationId: listProvisionedScimGroupsForAnEnterprise
tags:
- Enterprise
- Groups
- Lists
- Provisioned
- Scim
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
parameters:
- name: filter
description: >-
If specified, only results that match the specified filter will be
returned. Multiple filters are not supported. Possible filters are
`externalId`, `id`, and `displayName`. For example,
`?filter="externalId eq '9138790-10932-109120392-12321'"`.
in: query
required: false
schema:
type: string
examples:
displayName:
value: Engineering
externalId:
value: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
example: example_value
- $ref: '#/components/parameters/excluded-attributes'
- $ref: '#/components/parameters/start-index'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Success, either groups were found or not found
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-group-list'
examples:
default:
$ref: '#/components/examples/scim-enterprise-group-list'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Provision Scim Enterprise Group
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Creates a SCIM group for an enterprise.
If members are included as part of the group provisioning payload, they
will be created as external group members. It is up to a provider to
store a mapping between the `externalId` and `id` of each user.
operationId: provisionScimEnterpriseGroup
tags:
- Enterprise
- Groups
- Provision
- Scim
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#provision-a-scim-enterprise-group
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/group'
examples:
group:
value:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:Group
externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
displayName: Engineering
responses:
'201':
description: Group has been created
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-group-response'
examples:
group:
$ref: '#/components/examples/scim-enterprise-group'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/scim/v2/Groups/{scim_group_id}:
get:
summary: GitHub Get Scim Provisioning Information for an Enterprise Group
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Gets information about a SCIM group.
operationId: getScimProvisioningInformationForAnEnterpriseGroup
tags:
- Enterprise
- Get
- Groups
- Information
- Provisioning
- Scim
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-group
parameters:
- $ref: '#/components/parameters/scim-group-id'
- $ref: '#/components/parameters/excluded-attributes'
responses:
'200':
description: Success, a group was found
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-group-response'
examples:
default:
$ref: '#/components/examples/scim-enterprise-group'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Scim Information for Provisioned Enterprise Group
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* 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](#update-an-attribute-for-a-scim-enterprise-group) endpoint
instead.
operationId: setScimInformationForProvisionedEnterpriseGroup
tags:
- Enterprise
- Groups
- Information
- Provisioned
- Scim
- Sets
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-group
parameters:
- $ref: '#/components/parameters/scim-group-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/group'
examples:
group:
summary: Group
value:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:Group
externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
displayName: Engineering
groupWithMembers:
summary: Group with member
value:
schemas:
- urn:ietf:params:scim:schemas:core:2.0:Group
externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
displayName: Engineering
members:
- value: 879db59-3bdf-4490-ad68-ab880a2694745
displayName: User 1
- value: 0db508eb-91e2-46e4-809c-30dcbda0c685
displayName: User 2
responses:
'200':
description: Group was updated
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-group-response'
examples:
group:
$ref: '#/components/examples/scim-enterprise-group'
groupWithMembers:
$ref: '#/components/examples/scim-enterprise-group'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Attribute for Scim Enterprise Group
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Update 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](https://tools.ietf.org/html/rfc7644#section-3.5.2). Update can also be used to add group memberships.
Group memberships can be sent one at a time or in batches for faster
performance. **Note**: The memberships are referenced through a local
user `id`, and the user will need to be created before they are
referenced here.
operationId: updateAnAttributeForScimEnterpriseGroup
tags:
- Attribute
- Enterprise
- Groups
- Scim
- Update
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-group
parameters:
- $ref: '#/components/parameters/scim-group-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/patch-schema'
examples:
updateGroup:
summary: Update Group
value:
schemas:
- urn:ietf:params:scim:api:messages:2.0:PatchOp
Operations:
- op: replace
path: displayName
value: Employees
addMembers:
summary: Add Members
value:
schemas:
- urn:ietf:params:scim:api:messages:2.0:PatchOp
Operations:
- op: add
path: members
value:
- value: 879db59-3bdf-4490-ad68-ab880a2694745
- value: 0db508eb-91e2-46e4-809c-30dcbda0c685
responses:
'200':
description: Success, group was updated
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-group-response'
examples:
updateGroup:
$ref: '#/components/examples/scim-enterprise-group'
addMembers:
$ref: '#/components/examples/scim-enterprise-group'
'204':
description: Response
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Delete Scim Group from an Enterprise
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Deletes a SCIM group from an enterprise.
operationId: deleteScimGroupFromAnEnterprise
tags:
- Delete
- Enterprise
- Groups
- Scim
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#delete-a-scim-group-from-an-enterprise
parameters:
- $ref: '#/components/parameters/scim-group-id'
responses:
'204':
description: Group was deleted, no content
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/scim/v2/Users:
get:
summary: GitHub List Scim Provisioned Identities for an Enterprise
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Lists provisioned SCIM enterprise members.
When a user with a SCIM-provisioned external identity is removed from an
enterprise through a `patch` with `active` flag set to `false`, the
account's metadata is preserved to allow the user to re-join the
enterprise in the future. However, the user's account will be suspended
and the user will not be able to sign-in. In order to permanently
suspend the users account with no ability to re-join the enterprise in
the future, use the `delete` request. Users that were not permanently
deleted will be visible in the returned results.
operationId: listScimProvisionedIdentitiesForAnEnterprise
tags:
- Enterprise
- Identities
- Lists
- Provisioned
- Scim
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#list-scim-provisioned-identities-for-an-enterprise
parameters:
- name: filter
description: >-
If specified, only results that match the specified filter will be
returned. Multiple filters are not supported. Possible filters are
`userName`, `externalId`, `id`, and `displayName`. For example,
`?filter="externalId eq '9138790-10932-109120392-12321'"`.
in: query
required: false
schema:
type: string
examples:
userName:
value: userName eq 'E012345'
externalId:
value: externalId eq 'E012345'
example: example_value
- $ref: '#/components/parameters/start-index'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Success, either users were found or not found
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-user-list'
examples:
default:
$ref: '#/components/examples/scim-enterprise-user-list'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Provision Scim Enterprise User
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Creates an external identity for a new SCIM enterprise user.
SCIM does not authenticate users, it only provisions them. The
authentication of users is done by SAML. However, when SCIM is enabled,
all users need to be provisioned through SCIM before a user can sign in
through SAML. The matching of a user to a SCIM provisioned user is done
when the SAML assertion is consumed. The user will be matched on SAML
response `NameID` to SCIM `userName`.
When converting existing enterprise to use SCIM, the user handle
(`userName`) from the SCIM payload will be used to match the provisioned
user to an already existing user in the enterprise. Since the new
identity record is created for newly provisioned users the matching for
those records is done using a user's handle. Currently the matching will
be performed to all of the users no matter if they were SAML JIT
provisioned or created as local users.
operationId: provisionScimEnterpriseUser
tags:
- Enterprise
- Provision
- Scim
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#provision-a-scim-enterprise-user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/user'
examples:
user:
$ref: '#/components/examples/in-user'
enterpriseOwner:
$ref: '#/components/examples/in-user-owner'
responses:
'201':
description: User has been created
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-user-response'
examples:
user:
$ref: '#/components/examples/scim-enterprise-user'
enterpriseOwner:
$ref: '#/components/examples/scim-enterprise-user'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/scim/v2/Users/{scim_user_id}:
get:
summary: GitHub Get Scim Provisioning Information for an Enterprise User
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Gets information about a SCIM user.
operationId: getScimProvisioningInformationForAnEnterpriseUser
tags:
- Enterprise
- Get
- Information
- Provisioning
- Scim
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-user
parameters:
- $ref: '#/components/parameters/scim-user-id'
responses:
'200':
description: Success, a user was found
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-user-response'
examples:
default:
$ref: '#/components/examples/scim-enterprise-user'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Scim Information for Provisioned Enterprise User
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* 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](#update-an-attribute-for-a-scim-enterprise-user) endpoint instead.
**Warning:** Setting `active: false` will suspend a user and obfuscate
the user handle and user email. Since the implementation is a generic
SCIM implementation and does not differentiate yet between different IdP
providers, for Okta, the user GDPR data will not be purged and the
credentials will not be removed.
operationId: setScimInformationForProvisionedEnterpriseUser
tags:
- Enterprise
- Information
- Provisioned
- Scim
- Sets
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-user
parameters:
- $ref: '#/components/parameters/scim-user-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/user'
examples:
user:
$ref: '#/components/examples/in-user'
responses:
'200':
description: User was updated
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-user-response'
examples:
user:
$ref: '#/components/examples/scim-enterprise-user'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
summary: GitHub Update an Attribute for Scim Enterprise User
description: >-
**Note:** The SCIM API endpoints for enterprise accounts are currently
in *private* beta and are subject to change.
Update 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](https://tools.ietf.org/html/rfc7644#section-3.5.2).
**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:** Setting `active: false` will suspend a user and obfuscate
the user handle and user email. Since the implementation is a generic
SCIM implementation and does not differentiate yet between different IdP
providers, for Okta, the user GDPR data will not be purged and the
credentials will not be removed.
```
{
"Operations":[{
"op":"replace",
"value":{
"active":false
}
}]
}
```
operationId: updateAnAttributeForScimEnterpriseUser
tags:
- Attribute
- Enterprise
- Scim
- Update
- Users
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-user
parameters:
- $ref: '#/components/parameters/scim-user-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/patch-schema'
examples:
userMultiValuedProperties:
summary: Multi Valued Property
value:
schemas:
- urn:ietf:params:scim:api:messages:2.0:PatchOp
Operations:
- op: replace
path: emails[type eq 'work'].value
value: [email protected]
- op: replace
path: name.familyName
value: updatedFamilyName
userSingleValuedProperties:
summary: Single Valued Property
value:
schemas:
- urn:ietf:params:scim:api:messages:2.0:PatchOp
Operations:
- op: replace
path: userName
value: [email protected]
- op: replace
path: displayName
value: Monalisa Octocat
disableUser:
summary: Disable User
value:
schemas:
- urn:ietf:params:scim:api:messages:2.0:PatchOp
Operations:
- op: replace
path: active
value: false
responses:
'200':
description: Success, user was updated
content:
application/scim+json:
schema:
$ref: '#/components/schemas/scim-enterprise-user-response'
examples:
userMultiValuedProperties:
$ref: '#/components/examples/scim-enterprise-user'
userSingleValuedProperties:
$ref: '#/components/examples/scim-enterprise-user'
disableUser:
$ref: '#/components/examples/scim-enterprise-user'
'400':
$ref: '#/components/responses/scim_bad_request'
'401':
$ref: '#/components/responses/authorization_failure'
'403':
$ref: '#/components/responses/permission_denied'
'404':
$ref: '#/components/responses/not_found'
'409':
$ref: '#/components/responses/duplicate_record_detected'
'429':
$ref: '#/components/responses/scim_too_many_requests'
'500':
$ref: '#/components/responses/scim_internal_error'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: enterprise-admin
subcategory: scim
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: F
# --- truncated at 32 KB (4640 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-scim-openapi.yml