SCIM

SCIM Provisioning for Organizations

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

Please note that the SCIM API is available only to Business Plan with SAML SSO enabled.

Note: The SCIM API on GitHub is currently available for developers to preview. To access the API, you must provide a custom media type in the Accept header:

application/vnd.github.cloud-9-preview+json+scim

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Authenticating calls to the SCIM API

The API expects an OAuth 2.0 Bearer token to be passed to the Authorization header. You may also use Personal Access Tokens but they must be whitelisted from your token settings page

Mapping of SAML and SCIM data

Make sure to configure your SAML Identity Provider and your SCIM client to have identical NameID and userName for the same user. This provides the ability for a user authenticating using SAML to be linked to their identity that is already provisioned using SCIM.

Supported SCIM User attributes

Name Type Description
userName string The username for the user
name.givenName string User first name
name.lastName string User last name
emails array List of user emails
externalId string External identifier (generated by the SAML SSO provider)
id string Identifier generated by the GitHub SCIM endpoint
active boolean Used to indicate whether the identity is active (true) or should be deprovisioned (false)

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

GET /scim/v2/organizations/:organization/Users/:id

Get a list of provisioned identities

GET https://api.github.com/scim/v2/organizations/:organization/Users

Parameters

Name Type Description
startIndex integer Used for pagination: the index of the first result to return
count integer Used for pagination: the number of results to return
filter string Only eq type filters are supported

Filter parameter

You can filter results with the id, userName, emails and external_id query parameters.

GET https://api.github.com/scim/v2/organizations/:organization/Users?filter=userName eq user@example.com

Response

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

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": "8773fe-ffff-42837498757",
      "externalId": "239482347928374",
      "userName": "mona@example.com",
      "name": {
        "givenName": "mona",
        "familyName": "octocat"
      },
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2017-03-09T16:11:13-05:00",
        "lastModified": "2017-03-09T16:11:13-05:00"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "77563764-eb6-24-0598234-958243",
      "externalId": "sdfoiausdofiua",
      "userName": "hubot@example.com",
      "name": {
        "givenName": "hu",
        "familyName": "bot"
      },
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2017-03-09T16:11:13-05:00",
        "lastModified": "2017-03-09T16:11:13-05:00"
      }
    }
  ]
}

Get provisioning details for a single user

GET /scim/v2/organizations/:organization/Users/:id

Response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "77563764-eb6-24-0598234-958243",
  "externalId": "sdfoiausdofiua",
  "userName": "hubot@example.com",
  "name": {
    "givenName": "hu",
    "familyName": "bot"
  },
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00"
  }
}

Provision and invite users

Provision organization membership for and send activation emails to a list of email addresses.

POST /scim/v2/organizations/:organization/Users

Response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00"
  }
}

Update a provisioned organization membership

PUT /scim/v2/organizations/:organization/Users/:id

Note: Setting active: false removes the user from the organization, deletes the external identity, and deletes the associated :id.

Response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00"
  }
}

Update a user attribute

PATCH /scim/v2/organizations/:organization/Users/:id

Note: Setting active: false removes the user from the organization, deletes the external identity, and deletes the associated :id.

Response

Status: 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "edefdfedf-050c-11e7-8d32",
  "externalId": "a7d0f98382",
  "userName": "mona.octocat@okta.example.com",
  "name": {
    "givenName": "Mona",
    "familyName": "Octocat"
  },
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2017-03-09T16:11:13-05:00",
    "lastModified": "2017-03-09T16:11:13-05:00"
  }
}

Remove a user from the organization

DELETE /scim/v2/organizations/:organization/Users/:id

Response

Status: 204 No Content