diff --git a/descriptions/api.github.com/api.github.com.json b/descriptions/api.github.com/api.github.com.json index c295ecbea4..af3d9785c6 100644 --- a/descriptions/api.github.com/api.github.com.json +++ b/descriptions/api.github.com/api.github.com.json @@ -11951,6 +11951,14 @@ "application/json": { "schema": { "$ref": "#/components/schemas/interaction-limit" + }, + "examples": { + "default": { + "value": { + "limit": "collaborators_only", + "expiry": "one_month" + } + } } } } @@ -32903,6 +32911,15 @@ "description": "When forking from an existing repository, fork with only the default branch." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -42071,7 +42088,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -42079,6 +42096,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -45271,6 +45296,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -54315,6 +54348,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/api.github.com/api.github.com.yaml b/descriptions/api.github.com/api.github.com.yaml index 19f9f707ab..13bf899892 100644 --- a/descriptions/api.github.com/api.github.com.yaml +++ b/descriptions/api.github.com/api.github.com.yaml @@ -8711,6 +8711,11 @@ paths: application/json: schema: "$ref": "#/components/schemas/interaction-limit" + examples: + default: + value: + limit: collaborators_only + expiry: one_month responses: '200': description: Response @@ -23989,6 +23994,12 @@ paths: type: boolean description: When forking from an existing repository, fork with only the default branch. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -30361,12 +30372,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -32551,6 +32566,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -39265,6 +39285,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/api.github.com/dereferenced/api.github.com.deref.json b/descriptions/api.github.com/dereferenced/api.github.com.deref.json index fb7deb3f41..5233aea50f 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.deref.json +++ b/descriptions/api.github.com/dereferenced/api.github.com.deref.json @@ -74723,6 +74723,14 @@ "required": [ "limit" ] + }, + "examples": { + "default": { + "value": { + "limit": "collaborators_only", + "expiry": "one_month" + } + } } } } @@ -222247,6 +222255,15 @@ "description": "When forking from an existing repository, fork with only the default branch." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -322681,7 +322698,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -322689,6 +322706,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -347083,6 +347108,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -409665,6 +409698,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml b/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml index 2f874f2dac..ab7d859e43 100644 --- a/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml +++ b/descriptions/api.github.com/dereferenced/api.github.com.deref.yaml @@ -20438,6 +20438,11 @@ paths: - six_months required: - limit + examples: + default: + value: + limit: collaborators_only + expiry: one_month responses: '200': description: Response @@ -50864,6 +50869,12 @@ paths: type: boolean description: When forking from an existing repository, fork with only the default branch. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -63218,12 +63229,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -67842,6 +67857,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -78305,6 +78325,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghec/dereferenced/ghec.deref.json b/descriptions/ghec/dereferenced/ghec.deref.json index ee5ed6961a..72651a5187 100644 --- a/descriptions/ghec/dereferenced/ghec.deref.json +++ b/descriptions/ghec/dereferenced/ghec.deref.json @@ -50907,6 +50907,7 @@ "type": "object", "properties": { "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", "type": "array", "items": { "type": "string" @@ -50970,6 +50971,7 @@ "type": "object", "properties": { "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", "type": "array", "items": { "type": "string" @@ -76858,6 +76860,14 @@ "required": [ "limit" ] + }, + "examples": { + "default": { + "value": { + "limit": "collaborators_only", + "expiry": "one_month" + } + } } } } @@ -132022,15 +132032,15 @@ }, "/repos/{owner}/{repo}/actions/oidc/customization/sub": { "get": { - "summary": "Get the opt-out flag of an OIDC subject claim customization for a repository", - "description": "Gets the `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint.", + "summary": "Get the customization template for an OIDC subject claim for a repository", + "description": "Gets the customization template for an OpenID Connect (OIDC) subject claim.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint.", "tags": [ "actions" ], "operationId": "actions/get-custom-oidc-sub-claim-for-repo", "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository" + "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-a-repository" }, "parameters": [ { @@ -132058,12 +132068,20 @@ "content": { "application/json": { "schema": { - "title": "The json payload enables/disables the use of sub claim customization", - "description": "OIDC Customer Subject", + "title": "Actions OIDC subject customization for a repository", + "description": "Actions OIDC subject customization for a repository", "type": "object", "properties": { "use_default": { + "description": "Whether to use the default template or not. If `true`, the `include_claim_keys` field is ignored.", "type": "boolean" + }, + "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", + "type": "array", + "items": { + "type": "string" + } } }, "required": [ @@ -132073,7 +132091,11 @@ "examples": { "default": { "value": { - "use_default": false + "use_default": false, + "include_claim_keys": [ + "repo", + "context" + ] } } } @@ -132178,15 +132200,15 @@ } }, "put": { - "summary": "Set the opt-in flag of an OIDC subject claim customization for a repository", - "description": "Sets the `opt-in` or `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.", + "summary": "Set the customization template for an OIDC subject claim for a repository", + "description": "Sets the customization template and `opt-in` or `opt-out` flag for an OpenID Connect (OIDC) subject claim for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.", "tags": [ "actions" ], "operationId": "actions/set-custom-oidc-sub-claim-for-repo", "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository" + "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository" }, "parameters": [ { @@ -132213,12 +132235,20 @@ "content": { "application/json": { "schema": { - "title": "The json payload enables/disables the use of sub claim customization", - "description": "OIDC Customer Subject", + "title": "Actions OIDC subject customization for a repository", + "description": "Actions OIDC subject customization for a repository", "type": "object", "properties": { "use_default": { + "description": "Whether to use the default template or not. If `true`, the `include_claim_keys` field is ignored.", "type": "boolean" + }, + "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", + "type": "array", + "items": { + "type": "string" + } } }, "required": [ @@ -132228,7 +132258,11 @@ "examples": { "default": { "value": { - "use_default": false + "use_default": false, + "include_claim_keys": [ + "repo", + "context" + ] } } } @@ -225560,6 +225594,15 @@ "description": "When forking from an existing repository, fork with only the default branch." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -325994,7 +326037,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -326002,6 +326045,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -350396,6 +350447,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -356718,7 +356777,7 @@ } }, "400": { - "description": "Bad Request", + "description": "Bad request", "content": { "application/json": { "schema": { @@ -356791,7 +356850,7 @@ } }, "429": { - "description": "Too Many Requests", + "description": "Too many requests", "content": { "application/json": { "schema": { @@ -356873,7 +356932,7 @@ }, "post": { "summary": "Provision and invite a SCIM user", - "description": "Provision organization membership for a user, and send an activation email to the email address.", + "description": "Provisions organization membership for a user, and sends an activation email to the email address. If the user was previously a member of the organization, the invitation will reinstate any former privileges that the user had. For more information about reinstating former members, see \"[Reinstating a former member of your organization](https://docs.github.com/enterprise-cloud@latest//organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization).\"", "tags": [ "scim" ], @@ -357282,7 +357341,7 @@ } }, "500": { - "description": "Internal Error", + "description": "Internal server error", "content": { "application/json": { "schema": { @@ -357428,7 +357487,7 @@ } }, "400": { - "description": "Bad Request", + "description": "Bad request", "content": { "application/json": { "schema": { @@ -358982,7 +359041,7 @@ } }, "400": { - "description": "Bad Request", + "description": "Bad request", "content": { "application/json": { "schema": { @@ -416643,6 +416702,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghec/dereferenced/ghec.deref.yaml b/descriptions/ghec/dereferenced/ghec.deref.yaml index 689b5c6afa..9f2c85b00e 100644 --- a/descriptions/ghec/dereferenced/ghec.deref.yaml +++ b/descriptions/ghec/dereferenced/ghec.deref.yaml @@ -15564,6 +15564,8 @@ paths: type: object properties: include_claim_keys: + description: Array of unique strings. Each claim key can only + contain alphanumeric characters and underscores. type: array items: type: string @@ -21656,6 +21658,11 @@ paths: - six_months required: - limit + examples: + default: + value: + limit: collaborators_only + expiry: one_month responses: '200': description: Response @@ -32951,9 +32958,9 @@ paths: subcategory: workflow-runs "/repos/{owner}/{repo}/actions/oidc/customization/sub": get: - summary: Get the opt-out flag of an OIDC subject claim customization for a repository + summary: Get the customization template for an OIDC subject claim for a repository description: |- - Gets the `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository. + Gets the customization template for an OpenID Connect (OIDC) subject claim. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint. tags: @@ -32961,7 +32968,7 @@ paths: operationId: actions/get-custom-oidc-sub-claim-for-repo externalDocs: description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository + url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-a-repository parameters: - *214 - *215 @@ -32971,18 +32978,29 @@ paths: content: application/json: schema: &240 - title: The json payload enables/disables the use of sub claim customization - description: OIDC Customer Subject + title: Actions OIDC subject customization for a repository + description: Actions OIDC subject customization for a repository type: object properties: use_default: + description: Whether to use the default template or not. If `true`, + the `include_claim_keys` field is ignored. type: boolean + include_claim_keys: + description: Array of unique strings. Each claim key can only + contain alphanumeric characters and underscores. + type: array + items: + type: string required: - use_default examples: default: &241 value: use_default: false + include_claim_keys: + - repo + - context '400': *9 '404': *16 x-github: @@ -32992,9 +33010,9 @@ paths: category: actions subcategory: oidc put: - summary: Set the opt-in flag of an OIDC subject claim customization for a repository + summary: Set the customization template for an OIDC subject claim for a repository description: |- - Sets the `opt-in` or `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository. + Sets the customization template and `opt-in` or `opt-out` flag for an OpenID Connect (OIDC) subject claim for a repository. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint. tags: @@ -33002,7 +33020,7 @@ paths: operationId: actions/set-custom-oidc-sub-claim-for-repo externalDocs: description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository + url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository parameters: - *214 - *215 @@ -52346,6 +52364,12 @@ paths: type: boolean description: When forking from an existing repository, fork with only the default branch. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -64701,12 +64725,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -69326,6 +69354,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -71370,14 +71403,14 @@ paths: application/scim+json: schema: *457 '400': &461 - description: Bad Request + description: Bad request content: application/json: schema: *457 application/scim+json: schema: *457 '429': - description: Too Many Requests + description: Too many requests content: application/json: schema: *457 @@ -71390,8 +71423,11 @@ paths: subcategory: post: summary: Provision and invite a SCIM user - description: Provision organization membership for a user, and send an activation - email to the email address. + description: Provisions organization membership for a user, and sends an activation + email to the email address. If the user was previously a member of the organization, + the invitation will reinstate any former privileges that the user had. For + more information about reinstating former members, see "[Reinstating a former + member of your organization](https://docs.github.com/enterprise-cloud@latest//organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization)." tags: - scim operationId: scim/provision-and-invite-user @@ -71433,7 +71469,7 @@ paths: '404': *459 '403': *460 '500': - description: Internal Error + description: Internal server error content: application/json: schema: *457 @@ -80658,6 +80694,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghec/ghec.json b/descriptions/ghec/ghec.json index 9fc401e072..ee0be0667b 100644 --- a/descriptions/ghec/ghec.json +++ b/descriptions/ghec/ghec.json @@ -12719,6 +12719,14 @@ "application/json": { "schema": { "$ref": "#/components/schemas/interaction-limit" + }, + "examples": { + "default": { + "value": { + "limit": "collaborators_only", + "expiry": "one_month" + } + } } } } @@ -20924,15 +20932,15 @@ }, "/repos/{owner}/{repo}/actions/oidc/customization/sub": { "get": { - "summary": "Get the opt-out flag of an OIDC subject claim customization for a repository", - "description": "Gets the `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint.", + "summary": "Get the customization template for an OIDC subject claim for a repository", + "description": "Gets the customization template for an OpenID Connect (OIDC) subject claim.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint.", "tags": [ "actions" ], "operationId": "actions/get-custom-oidc-sub-claim-for-repo", "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository" + "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-a-repository" }, "parameters": [ { @@ -20948,11 +20956,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/opt-out-oidc-custom-sub" + "$ref": "#/components/schemas/oidc-custom-sub-repo" }, "examples": { "default": { - "$ref": "#/components/examples/opt-out-oidc-custom-sub" + "$ref": "#/components/examples/oidc-custom-sub-repo" } } } @@ -20976,15 +20984,15 @@ } }, "put": { - "summary": "Set the opt-in flag of an OIDC subject claim customization for a repository", - "description": "Sets the `opt-in` or `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.", + "summary": "Set the customization template for an OIDC subject claim for a repository", + "description": "Sets the customization template and `opt-in` or `opt-out` flag for an OpenID Connect (OIDC) subject claim for a repository.\nYou must authenticate using an access token with the `repo` scope to use this\nendpoint. GitHub Apps must have the `actions:write` permission to use this endpoint.", "tags": [ "actions" ], "operationId": "actions/set-custom-oidc-sub-claim-for-repo", "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository" + "url": "https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository" }, "parameters": [ { @@ -20999,11 +21007,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/opt-out-oidc-custom-sub" + "$ref": "#/components/schemas/oidc-custom-sub-repo" }, "examples": { "default": { - "$ref": "#/components/examples/opt-out-oidc-custom-sub" + "$ref": "#/components/examples/oidc-custom-sub-repo" } } } @@ -34137,6 +34145,15 @@ "description": "When forking from an existing repository, fork with only the default branch." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -43305,7 +43322,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -43313,6 +43330,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -46505,6 +46530,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -48011,7 +48044,7 @@ }, "post": { "summary": "Provision and invite a SCIM user", - "description": "Provision organization membership for a user, and send an activation email to the email address.", + "description": "Provisions organization membership for a user, and sends an activation email to the email address. If the user was previously a member of the organization, the invitation will reinstate any former privileges that the user had. For more information about reinstating former members, see \"[Reinstating a former member of your organization](https://docs.github.com/enterprise-cloud@latest//organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization).\"", "tags": [ "scim" ], @@ -56373,6 +56406,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } @@ -66288,6 +66332,7 @@ "type": "object", "properties": { "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", "type": "array", "items": { "type": "string" @@ -71914,13 +71959,21 @@ "runner_group_name" ] }, - "opt-out-oidc-custom-sub": { - "title": "The json payload enables/disables the use of sub claim customization", - "description": "OIDC Customer Subject", + "oidc-custom-sub-repo": { + "title": "Actions OIDC subject customization for a repository", + "description": "Actions OIDC subject customization for a repository", "type": "object", "properties": { "use_default": { + "description": "Whether to use the default template or not. If `true`, the `include_claim_keys` field is ignored.", "type": "boolean" + }, + "include_claim_keys": { + "description": "Array of unique strings. Each claim key can only contain alphanumeric characters and underscores.", + "type": "array", + "items": { + "type": "string" + } } }, "required": [ @@ -97023,9 +97076,13 @@ "runner_group_name": "my runner group" } }, - "opt-out-oidc-custom-sub": { + "oidc-custom-sub-repo": { "value": { - "use_default": false + "use_default": false, + "include_claim_keys": [ + "repo", + "context" + ] } }, "actions-repository-permissions": { @@ -112803,7 +112860,7 @@ } }, "scim_bad_request": { - "description": "Bad Request", + "description": "Bad request", "content": { "application/json": { "schema": { @@ -112818,7 +112875,7 @@ } }, "scim_too_many_requests": { - "description": "Too Many Requests", + "description": "Too many requests", "content": { "application/json": { "schema": { @@ -112833,7 +112890,7 @@ } }, "scim_internal_error": { - "description": "Internal Error", + "description": "Internal server error", "content": { "application/json": { "schema": { diff --git a/descriptions/ghec/ghec.yaml b/descriptions/ghec/ghec.yaml index 2519bfa482..f975444466 100644 --- a/descriptions/ghec/ghec.yaml +++ b/descriptions/ghec/ghec.yaml @@ -9247,6 +9247,11 @@ paths: application/json: schema: "$ref": "#/components/schemas/interaction-limit" + examples: + default: + value: + limit: collaborators_only + expiry: one_month responses: '200': description: Response @@ -15079,9 +15084,9 @@ paths: subcategory: workflow-runs "/repos/{owner}/{repo}/actions/oidc/customization/sub": get: - summary: Get the opt-out flag of an OIDC subject claim customization for a repository + summary: Get the customization template for an OIDC subject claim for a repository description: |- - Gets the `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository. + Gets the customization template for an OpenID Connect (OIDC) subject claim. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `organization_administration:read` permission to use this endpoint. tags: @@ -15089,7 +15094,7 @@ paths: operationId: actions/get-custom-oidc-sub-claim-for-repo externalDocs: description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository + url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#get-the-customization-template-for-an-oidc-subject-claim-for-a-repository parameters: - "$ref": "#/components/parameters/owner" - "$ref": "#/components/parameters/repo" @@ -15099,10 +15104,10 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/opt-out-oidc-custom-sub" + "$ref": "#/components/schemas/oidc-custom-sub-repo" examples: default: - "$ref": "#/components/examples/opt-out-oidc-custom-sub" + "$ref": "#/components/examples/oidc-custom-sub-repo" '400': "$ref": "#/components/responses/bad_request" '404': @@ -15114,9 +15119,9 @@ paths: category: actions subcategory: oidc put: - summary: Set the opt-in flag of an OIDC subject claim customization for a repository + summary: Set the customization template for an OIDC subject claim for a repository description: |- - Sets the `opt-in` or `opt-out` flag of a GitHub Actions OpenID Connect (OIDC) subject claim customization for a repository. + Sets the customization template and `opt-in` or `opt-out` flag for an OpenID Connect (OIDC) subject claim for a repository. You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint. tags: @@ -15124,7 +15129,7 @@ paths: operationId: actions/set-custom-oidc-sub-claim-for-repo externalDocs: description: API method documentation - url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-opt-out-flag-of-an-oidc-subject-claim-customization-for-a-repository + url: https://docs.github.com/enterprise-cloud@latest//rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository parameters: - "$ref": "#/components/parameters/owner" - "$ref": "#/components/parameters/repo" @@ -15133,10 +15138,10 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/opt-out-oidc-custom-sub" + "$ref": "#/components/schemas/oidc-custom-sub-repo" examples: default: - "$ref": "#/components/examples/opt-out-oidc-custom-sub" + "$ref": "#/components/examples/oidc-custom-sub-repo" responses: '201': description: Empty response @@ -24850,6 +24855,12 @@ paths: type: boolean description: When forking from an existing repository, fork with only the default branch. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -31223,12 +31234,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -33414,6 +33429,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -34529,8 +34549,11 @@ paths: subcategory: post: summary: Provision and invite a SCIM user - description: Provision organization membership for a user, and send an activation - email to the email address. + description: Provisions organization membership for a user, and sends an activation + email to the email address. If the user was previously a member of the organization, + the invitation will reinstate any former privileges that the user had. For + more information about reinstating former members, see "[Reinstating a former + member of your organization](https://docs.github.com/enterprise-cloud@latest//organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization)." tags: - scim operationId: scim/provision-and-invite-user @@ -40733,6 +40756,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response @@ -48261,6 +48292,8 @@ components: type: object properties: include_claim_keys: + description: Array of unique strings. Each claim key can only contain alphanumeric + characters and underscores. type: array items: type: string @@ -52733,13 +52766,21 @@ components: - runner_name - runner_group_id - runner_group_name - opt-out-oidc-custom-sub: - title: The json payload enables/disables the use of sub claim customization - description: OIDC Customer Subject + oidc-custom-sub-repo: + title: Actions OIDC subject customization for a repository + description: Actions OIDC subject customization for a repository type: object properties: use_default: + description: Whether to use the default template or not. If `true`, the + `include_claim_keys` field is ignored. type: boolean + include_claim_keys: + description: Array of unique strings. Each claim key can only contain alphanumeric + characters and underscores. + type: array + items: + type: string required: - use_default actions-enabled: @@ -73267,9 +73308,12 @@ components: runner_name: my runner runner_group_id: 2 runner_group_name: my runner group - opt-out-oidc-custom-sub: + oidc-custom-sub-repo: value: use_default: false + include_claim_keys: + - repo + - context actions-repository-permissions: value: enabled: true @@ -86779,7 +86823,7 @@ components: schema: "$ref": "#/components/schemas/scim-error" scim_bad_request: - description: Bad Request + description: Bad request content: application/json: schema: @@ -86788,7 +86832,7 @@ components: schema: "$ref": "#/components/schemas/scim-error" scim_too_many_requests: - description: Too Many Requests + description: Too many requests content: application/json: schema: @@ -86797,7 +86841,7 @@ components: schema: "$ref": "#/components/schemas/scim-error" scim_internal_error: - description: Internal Error + description: Internal server error content: application/json: schema: diff --git a/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.json b/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.json index 12c143ff47..e3e0cdf74b 100644 --- a/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.json +++ b/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.json @@ -183211,6 +183211,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -277258,7 +277267,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -277266,6 +277275,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -300370,6 +300387,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -338407,6 +338432,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.yaml b/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.yaml index 5b0dc82d24..6f8386cc03 100644 --- a/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.yaml +++ b/descriptions/ghes-3.2/dereferenced/ghes-3.2.deref.yaml @@ -42777,6 +42777,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -54080,12 +54086,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -58432,6 +58442,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -66622,6 +66637,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.2/ghes-3.2.json b/descriptions/ghes-3.2/ghes-3.2.json index 92a7844428..719bce8aac 100644 --- a/descriptions/ghes-3.2/ghes-3.2.json +++ b/descriptions/ghes-3.2/ghes-3.2.json @@ -28724,6 +28724,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -37208,7 +37217,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -37216,6 +37225,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -40225,6 +40242,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -46968,6 +46993,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.2/ghes-3.2.yaml b/descriptions/ghes-3.2/ghes-3.2.yaml index c51ca740c5..e47b0c639b 100644 --- a/descriptions/ghes-3.2/ghes-3.2.yaml +++ b/descriptions/ghes-3.2/ghes-3.2.yaml @@ -21079,6 +21079,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -27189,12 +27195,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -29251,6 +29261,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -34360,6 +34375,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.json b/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.json index 5510a65333..896f207410 100644 --- a/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.json +++ b/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.json @@ -184834,6 +184834,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -279030,7 +279039,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -279038,6 +279047,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -302525,6 +302542,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -340410,6 +340435,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.yaml b/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.yaml index f2d7d2e57b..d26ea59cdd 100644 --- a/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.yaml +++ b/descriptions/ghes-3.3/dereferenced/ghes-3.3.deref.yaml @@ -43238,6 +43238,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -54560,12 +54566,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -59100,6 +59110,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -67252,6 +67267,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.3/ghes-3.3.json b/descriptions/ghes-3.3/ghes-3.3.json index a3cbca0202..1f59ad91cd 100644 --- a/descriptions/ghes-3.3/ghes-3.3.json +++ b/descriptions/ghes-3.3/ghes-3.3.json @@ -28532,6 +28532,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -36926,7 +36935,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -36934,6 +36943,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -40080,6 +40097,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -46665,6 +46690,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.3/ghes-3.3.yaml b/descriptions/ghes-3.3/ghes-3.3.yaml index 4aae3f4627..79e5530cdb 100644 --- a/descriptions/ghes-3.3/ghes-3.3.yaml +++ b/descriptions/ghes-3.3/ghes-3.3.yaml @@ -20446,6 +20446,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -26233,12 +26239,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -28382,6 +28392,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -33265,6 +33280,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.json b/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.json index aee9fa63b0..a1e71112d7 100644 --- a/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.json +++ b/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.json @@ -197761,6 +197761,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -291949,7 +291958,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -291957,6 +291966,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -315643,6 +315660,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -357725,6 +357750,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.yaml b/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.yaml index 6c81d1551c..1e3aeefc98 100644 --- a/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.yaml +++ b/descriptions/ghes-3.4/dereferenced/ghes-3.4.deref.yaml @@ -45513,6 +45513,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -56835,12 +56841,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -61442,6 +61452,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -70104,6 +70119,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.4/ghes-3.4.json b/descriptions/ghes-3.4/ghes-3.4.json index 992b9b7585..72ea397cc7 100644 --- a/descriptions/ghes-3.4/ghes-3.4.json +++ b/descriptions/ghes-3.4/ghes-3.4.json @@ -30396,6 +30396,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -38790,7 +38799,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -38798,6 +38807,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -42070,6 +42087,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -48956,6 +48981,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.4/ghes-3.4.yaml b/descriptions/ghes-3.4/ghes-3.4.yaml index 0dd1649687..861791938f 100644 --- a/descriptions/ghes-3.4/ghes-3.4.yaml +++ b/descriptions/ghes-3.4/ghes-3.4.yaml @@ -21946,6 +21946,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -27733,12 +27739,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -29957,6 +29967,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -35071,6 +35086,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.json b/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.json index f70fc2134b..85ab7f28d1 100644 --- a/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.json +++ b/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.json @@ -203996,6 +203996,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -298196,7 +298205,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -298204,6 +298213,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -321904,6 +321921,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -364428,6 +364453,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.yaml b/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.yaml index 651a09e205..6e0b055885 100644 --- a/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.yaml +++ b/descriptions/ghes-3.5/dereferenced/ghes-3.5.deref.yaml @@ -46896,6 +46896,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -58218,12 +58224,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -62840,6 +62850,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -71640,6 +71655,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.5/ghes-3.5.json b/descriptions/ghes-3.5/ghes-3.5.json index a780dadcf0..250bd6b10e 100644 --- a/descriptions/ghes-3.5/ghes-3.5.json +++ b/descriptions/ghes-3.5/ghes-3.5.json @@ -31461,6 +31461,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -39855,7 +39864,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -39863,6 +39872,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -43135,6 +43152,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -50192,6 +50217,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.5/ghes-3.5.yaml b/descriptions/ghes-3.5/ghes-3.5.yaml index 39790041ed..0582ac0951 100644 --- a/descriptions/ghes-3.5/ghes-3.5.yaml +++ b/descriptions/ghes-3.5/ghes-3.5.yaml @@ -22694,6 +22694,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -28481,12 +28487,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -30713,6 +30723,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -35942,6 +35957,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.json b/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.json index 33f685aed0..1058fc8969 100644 --- a/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.json +++ b/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.json @@ -208363,6 +208363,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -303789,7 +303798,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -303797,6 +303806,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -328248,6 +328265,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -333168,7 +333193,7 @@ "/scim/v2/enterprises/{enterprise}/Groups": { "get": { "summary": "List provisioned SCIM groups for an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nLists provisioned SCIM groups in an enterprise.\n\nYou can improve query search time by using the `excludedAttributes` query parameter with a value of `members` to exclude members from the response.", "operationId": "enterprise-admin/list-provisioned-groups-enterprise", "tags": [ "enterprise-admin" @@ -333179,46 +333204,61 @@ }, "parameters": [ { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, + "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" + } } }, { - "name": "startIndex", - "description": "Used for pagination: the index of the first result to return.", + "name": "excludedAttributes", + "description": "Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "string", + "example": "members" } }, { - "name": "count", - "description": "Used for pagination: the number of results to return.", + "name": "startIndex", + "description": "Used for pagination: the starting index of the first result to return when paginating through values.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "integer", + "default": 1, + "format": "int32", + "example": 1 } }, { - "name": "filter", - "description": "filter results", + "name": "count", + "description": "Used for pagination: the number of results to return per page.", "in": "query", "required": false, "schema": { - "type": "string" + "type": "integer", + "default": 30, + "format": "int32", + "example": 1 } }, { - "name": "excludedAttributes", - "description": "attributes to exclude", - "in": "query", - "required": false, + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -333226,97 +333266,176 @@ ], "responses": { "200": { - "description": "Response", + "description": "Success, either groups were found or not found", "content": { "application/json": { "schema": { "type": "object", + "required": [ + "schemas", + "totalResults", + "Resources", + "startIndex", + "itemsPerPage" + ], "properties": { "schemas": { "type": "array", + "description": "The URIs that are used to indicate the namespaces of the list SCIM schemas.", "items": { - "type": "string" - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] + }, + "example": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] }, "totalResults": { - "type": "number" - }, - "itemsPerPage": { - "type": "number" - }, - "startIndex": { - "type": "number" + "type": "integer", + "description": "Number of results found", + "example": 1 }, "Resources": { "type": "array", + "description": "Information about each provisioned group.", "items": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string", - "nullable": true - }, - "displayName": { - "type": "string" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "display": { - "type": "string" + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { + "type": "array", + "description": "The group members.", + "items": { + "type": "object", + "required": [ + "value", + "displayName" + ], + "properties": { + "value": { + "type": "string", + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" + } + } } } } }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta", + "members" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] }, - "location": { - "type": "string" + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } } } } - }, - "required": [ - "schemas", - "id" ] } + }, + "startIndex": { + "type": "integer", + "description": "A starting index for the returned page", + "example": 1 + }, + "itemsPerPage": { + "type": "integer", + "description": "Number of objects per page", + "example": 20 } - }, - "required": [ - "schemas", - "totalResults", - "itemsPerPage", - "startIndex", - "Resources" - ] + } }, "examples": { "default": { @@ -333324,58 +333443,262 @@ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], - "totalResults": 2, - "itemsPerPage": 2, - "startIndex": 1, + "totalResults": 1, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "id": "927fa2c08dcb4a7fae9e", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "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" + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" } } - ] + ], + "startIndex": 1, + "itemsPerPage": 20 + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } } } } @@ -333391,8 +333714,8 @@ } }, "post": { - "summary": "Provision a SCIM enterprise group and invite users", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nProvision 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.", + "summary": "Provision a SCIM enterprise group", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nCreates a SCIM group for an enterprise.\n\nIf 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": "enterprise-admin/provision-and-invite-enterprise-group", "tags": [ "enterprise-admin" @@ -333418,54 +333741,69 @@ "application/json": { "schema": { "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], "properties": { "schemas": { "type": "array", - "description": "The SCIM schema URIs.", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", "items": { - "type": "string" - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" }, "displayName": { "type": "string", - "description": "The name of the SCIM group. This must match the GitHub organization that the group maps to." + "description": "A human-readable name for a security group.", + "example": "Engineering" }, "members": { "type": "array", + "description": "The group members.", "items": { "type": "object", + "required": [ + "value", + "displayName" + ], "properties": { "value": { "type": "string", - "description": "The SCIM user ID for a user." + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" } - }, - "required": [ - "value" - ] + } } } - }, - "required": [ - "schemas", - "displayName" - ] + } }, "examples": { - "default": { + "group": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "displayName": "octo-org", - "members": [ - { - "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc" - }, - { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" - } - ] + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering" } } } @@ -333474,94 +333812,387 @@ }, "responses": { "201": { - "description": "Response", + "description": "Group has been created", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string", - "nullable": true - }, - "displayName": { - "type": "string" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "display": { - "type": "string" + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { + "type": "array", + "description": "The group members.", + "items": { + "type": "object", + "required": [ + "value", + "displayName" + ], + "properties": { + "value": { + "type": "string", + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" + } + } } } } }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta", + "members" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] }, - "location": { - "type": "string" + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } } } } - }, - "required": [ - "schemas", - "id" ] }, "examples": { - "default": { + "group": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "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" + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } } @@ -333581,7 +334212,7 @@ "/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}": { "get": { "summary": "Get SCIM provisioning information for an enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nGets information about a SCIM group.", "operationId": "enterprise-admin/get-provisioning-information-for-enterprise-group", "tags": [ "enterprise-admin" @@ -333602,85 +334233,142 @@ }, { "name": "scim_group_id", - "description": "Identifier generated by the GitHub SCIM endpoint.", + "description": "A unique identifier of the SCIM group.", "in": "path", "required": true, "schema": { - "type": "string" - } - }, - { - "name": "excludedAttributes", - "description": "Attributes to exclude.", - "in": "query", - "required": false, - "schema": { - "type": "string" + "type": "string", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" } } ], "responses": { "200": { - "description": "Response", + "description": "Success, a group was found", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string", - "nullable": true - }, - "displayName": { - "type": "string" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "display": { - "type": "string" + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { + "type": "array", + "description": "The group members.", + "items": { + "type": "object", + "required": [ + "value", + "displayName" + ], + "properties": { + "value": { + "type": "string", + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" + } + } } } } }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta", + "members" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] }, - "location": { - "type": "string" + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } } } } - }, - "required": [ - "schemas", - "id" ] }, "examples": { @@ -333690,221 +334378,276 @@ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "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" + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" } } } } } } - } - }, - "x-github": { - "enabledForGitHubApps": true, - "githubCloudOnly": false, - "category": "enterprise-admin", - "subcategory": "scim" - } - }, - "put": { - "summary": "Set SCIM information for a provisioned enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nReplaces 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": "enterprise-admin/set-information-for-provisioned-enterprise-group", - "tags": [ - "enterprise-admin" - ], - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-group" - }, - "parameters": [ - { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } }, - { - "name": "scim_group_id", - "description": "Identifier generated by the GitHub SCIM endpoint.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "displayName": { - "type": "string", - "description": "The name of the SCIM group. This must match the GitHub organization that the group maps to." - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The SCIM user ID for a user." - } - }, - "required": [ - "value" - ] + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } } } - }, - "required": [ - "schemas", - "displayName" - ] + } }, - "examples": { - "default": { - "value": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:Group" - ], - "displayName": "octo-org", - "members": [ - { - "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc" - }, - { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } - ] + } } } } } - } - }, - "responses": { - "200": { - "description": "Response", + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "429": { + "description": "Too many requests", "content": { "application/json": { "schema": { + "title": "Scim Error", + "description": "Scim Error", "type": "object", "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, "schemas": { "type": "array", "items": { "type": "string" } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "id": { - "type": "string" + "documentation_url": { + "type": "string", + "nullable": true }, - "externalId": { + "detail": { "type": "string", "nullable": true }, - "displayName": { - "type": "string" + "status": { + "type": "integer" }, - "members": { + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" - }, - "display": { - "type": "string" - } - } + "type": "string" } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } - }, - "required": [ - "schemas", - "id" - ] - }, - "examples": { - "default": { - "value": { - "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" + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } } @@ -333920,16 +334663,16 @@ "subcategory": "scim" } }, - "patch": { - "summary": "Update an attribute for a SCIM enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nAllows 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](https://tools.ietf.org/html/rfc7644#section-3.5.2).", - "operationId": "enterprise-admin/update-attribute-for-enterprise-group", + "put": { + "summary": "Set SCIM information for a provisioned enterprise group", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nReplaces an existing provisioned group’s information.\n\nYou 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": "enterprise-admin/set-information-for-provisioned-enterprise-group", "tags": [ "enterprise-admin" ], "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-group" + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-group" }, "parameters": [ { @@ -333943,11 +334686,12 @@ }, { "name": "scim_group_id", - "description": "Identifier generated by the GitHub SCIM endpoint.", + "description": "A unique identifier of the SCIM group.", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" } } ], @@ -333957,65 +334701,88 @@ "application/json": { "schema": { "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], "properties": { "schemas": { "type": "array", - "description": "The SCIM schema URIs.", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", "items": { - "type": "string" - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "Operations": { + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { "type": "array", - "description": "Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2).", - "minItems": 1, + "description": "The group members.", "items": { "type": "object", + "required": [ + "value", + "displayName" + ], "properties": { - "op": { + "value": { "type": "string", - "enum": [ - "add", - "Add", - "remove", - "Remove", - "replace", - "Replace" - ] - }, - "path": { - "type": "string" + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" }, - "value": { - "description": "Can be any value - string, number, array or object." + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" } - }, - "required": [ - "op" - ] + } } } - }, - "required": [ - "schemas", - "Operations" - ] + } }, "examples": { - "default": { + "group": { + "summary": "Group", "value": { "schemas": [ - "urn:ietf:params:scim:api:messages:2.0:PatchOp" + "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "Operations": [ + "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": [ { - "op": "remove", - "path": "members", - "value": [ - { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" - } - ] + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ] } @@ -334026,138 +334793,1317 @@ }, "responses": { "200": { - "description": "Response", + "description": "Group was updated", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string", - "nullable": true - }, - "displayName": { - "type": "string" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "display": { - "type": "string" + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { + "type": "array", + "description": "The group members.", + "items": { + "type": "object", + "required": [ + "value", + "displayName" + ], + "properties": { + "value": { + "type": "string", + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" + } + } } } } }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta", + "members" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] }, - "location": { - "type": "string" + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } } } } - }, - "required": [ - "schemas", - "id" ] }, "examples": { - "default": { + "group": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ], + "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", + "members": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ], + "meta": { + "resourceType": "Group", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" + } + } + }, + "groupWithMembers": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" } } } } } } - } - }, - "x-github": { - "enabledForGitHubApps": true, - "githubCloudOnly": false, - "category": "enterprise-admin", - "subcategory": "scim" - } - }, - "delete": { - "summary": "Delete a SCIM group from an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", - "operationId": "enterprise-admin/delete-scim-group-from-enterprise", - "tags": [ - "enterprise-admin" - ], - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-group-from-an-enterprise" - }, - "parameters": [ - { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "x-github": { + "enabledForGitHubApps": true, + "githubCloudOnly": false, + "category": "enterprise-admin", + "subcategory": "scim" + } + }, + "patch": { + "summary": "Update an attribute for a SCIM enterprise group", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nUpdate a provisioned group’s individual attributes.\n\nTo 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.\n\nGroup 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": "enterprise-admin/update-attribute-for-enterprise-group", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-group" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } }, { "name": "scim_group_id", - "description": "Identifier generated by the GitHub SCIM endpoint.", + "description": "A unique identifier of the SCIM group.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "Operations", + "schemas" + ], + "properties": { + "Operations": { + "type": "array", + "description": "patch operations list", + "items": { + "type": "object", + "required": [ + "op" + ], + "properties": { + "op": { + "type": "string", + "enum": [ + "add", + "replace", + "remove" + ] + }, + "path": { + "type": "string" + }, + "value": { + "type": "string", + "description": "Corresponding 'value' of that field specified by 'path'" + } + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:PatchOp" + ] + } + } + } + }, + "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/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" + }, + "members": { + "type": "array", + "description": "The group members.", + "items": { + "type": "object", + "required": [ + "value", + "displayName" + ], + "properties": { + "value": { + "type": "string", + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" + }, + "displayName": { + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" + } + } + } + } + } + }, + { + "type": "object", + "required": [ + "id", + "meta", + "members" + ], + "properties": { + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + }, + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] + }, + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + } + } + } + ] + }, + "examples": { + "updateGroup": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ], + "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", + "members": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ], + "meta": { + "resourceType": "Group", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" + } + } + }, + "addMembers": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ], + "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", + "members": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ], + "meta": { + "resourceType": "Group", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "x-github": { + "enabledForGitHubApps": true, + "githubCloudOnly": false, + "category": "enterprise-admin", + "subcategory": "scim" + } + }, + "delete": { + "summary": "Delete a SCIM group from an enterprise", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\n Deletes a SCIM group from an enterprise.", + "operationId": "enterprise-admin/delete-scim-group-from-enterprise", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-group-from-an-enterprise" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", "in": "path", "required": true, "schema": { "type": "string" } + }, + { + "name": "scim_group_id", + "description": "A unique identifier of the SCIM group.", + "in": "path", + "required": true, + "schema": { + "type": "string", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + } } ], "responses": { "204": { - "description": "Response" + "description": "Group was deleted, no content" + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } } }, "x-github": { @@ -334171,7 +336117,7 @@ "/scim/v2/enterprises/{enterprise}/Users": { "get": { "summary": "List SCIM provisioned identities for an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nRetrieves a paginated list of all provisioned enterprise members, including pending invitations.\n\nWhen 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 Enterprise Server. This can happen in certain cases where an external identity associated with an organization will not match an organization member:\n - 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.\n - 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).\n - 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.\n\nThe 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 Enterprise Server account after completing SSO:\n\n1. The user is granted access by the IdP and is not a member of the GitHub Enterprise Server enterprise.\n\n1. The user attempts to access the GitHub Enterprise Server enterprise and initiates the SAML SSO process, and is not currently signed in to their GitHub Enterprise Server account.\n\n1. 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 Enterprise Server account:\n - If the user signs in, their GitHub Enterprise Server account is linked to this entry.\n - If the user does not sign in (or does not create a new account when prompted), they are not added to the GitHub Enterprise Server enterprise, and the external identity `null` entry remains in place.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nLists provisioned SCIM enterprise members.\n\nWhen 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.\n\nYou can improve query search time by using the `excludedAttributes` query parameter with a value of `groups` to exclude groups from the response.", "operationId": "enterprise-admin/list-provisioned-identities-enterprise", "tags": [ "enterprise-admin" @@ -334182,232 +336128,2509 @@ }, "parameters": [ { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, + "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'" + } + } + }, + { + "name": "excludedAttributes", + "description": "Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "example": "members" } }, { "name": "startIndex", - "description": "Used for pagination: the index of the first result to return.", + "description": "Used for pagination: the starting index of the first result to return when paginating through values.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "integer", + "default": 1, + "format": "int32", + "example": 1 } }, { "name": "count", - "description": "Used for pagination: the number of results to return.", + "description": "Used for pagination: the number of results to return per page.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "integer", + "default": 30, + "format": "int32", + "example": 1 + } + }, + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success, either users were found or not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "schemas", + "totalResults", + "Resources", + "startIndex", + "itemsPerPage" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the list SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] + }, + "example": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] + }, + "totalResults": { + "type": "integer", + "description": "Number of results found", + "example": 1 + }, + "Resources": { + "type": "array", + "description": "Information about each provisioned account.", + "items": { + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + { + "type": "object", + "required": [ + "id", + "meta" + ], + "properties": { + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + }, + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." + }, + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + } + } + } + ] + } + }, + "startIndex": { + "type": "integer", + "description": "A starting index for the returned page", + "example": 1 + }, + "itemsPerPage": { + "type": "integer", + "description": "Number of objects per page", + "example": 20 + } + } + }, + "examples": { + "default": { + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 1, + "Resources": [ + { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "externalId": "E012345", + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ] + } + ], + "startIndex": 1, + "itemsPerPage": 20 + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "x-github": { + "enabledForGitHubApps": true, + "githubCloudOnly": false, + "category": "enterprise-admin", + "subcategory": "scim" + } + }, + "post": { + "summary": "Provision a SCIM enterprise user", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nCreates an external identity for a new SCIM enterprise user.\n\nSCIM 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`.\n\nWhen 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": "enterprise-admin/provision-and-invite-enterprise-user", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#provision-and-invite-a-scim-enterprise-user" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + "examples": { + "user": { + "summary": "User", + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ] + } + }, + "enterpriseOwner": { + "summary": "Enterprise Owner", + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "Enterprise Owner", + "primary": false + } + ] + } + } + } + } + } + }, + "responses": { + "201": { + "description": "User has been created", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + { + "type": "object", + "required": [ + "id", + "meta" + ], + "properties": { + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + }, + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." + }, + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + } + } + } + ] + }, + "examples": { + "user": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ], + "meta": { + "resourceType": "User", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" + } + } + }, + "enterpriseOwner": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ], + "meta": { + "resourceType": "User", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "x-github": { + "enabledForGitHubApps": true, + "githubCloudOnly": false, + "category": "enterprise-admin", + "subcategory": "scim" + } + } + }, + "/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}": { + "get": { + "summary": "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.\n\nGets information about a SCIM user.", + "operationId": "enterprise-admin/get-provisioning-information-for-enterprise-user", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#get-scim-provisioning-information-for-an-enterprise-user" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "scim_user_id", + "description": "The unique identifier of the SCIM user.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success, a user was found", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + { + "type": "object", + "required": [ + "id", + "meta" + ], + "properties": { + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + }, + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." + }, + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ], + "meta": { + "resourceType": "User", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + }, + "x-github": { + "enabledForGitHubApps": true, + "githubCloudOnly": false, + "category": "enterprise-admin", + "subcategory": "scim" + } + }, + "put": { + "summary": "Set SCIM information for a provisioned enterprise user", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nReplaces an existing provisioned user's information.\n\nYou 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.\n\n**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": "enterprise-admin/set-information-for-provisioned-enterprise-user", + "tags": [ + "enterprise-admin" + ], + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-user" + }, + "parameters": [ + { + "name": "enterprise", + "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "scim_user_id", + "description": "The unique identifier of the SCIM user.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + "examples": { + "user": { + "summary": "User", + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "User was updated", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], + "properties": { + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + } + } + }, + { + "type": "object", + "required": [ + "id", + "meta" + ], + "properties": { + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" + }, + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." + }, + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + } + } + } + ] + }, + "examples": { + "user": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "User", + "primary": false + } + ], + "meta": { + "resourceType": "User", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" + } + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } } }, - { - "name": "filter", - "description": "filter results", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Response", + "500": { + "description": "Internal server error", "content": { "application/json": { "schema": { + "title": "Scim Error", + "description": "Scim Error", "type": "object", "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, "schemas": { "type": "array", "items": { "type": "string" } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "totalResults": { - "type": "number" + "documentation_url": { + "type": "string", + "nullable": true }, - "itemsPerPage": { - "type": "number" + "detail": { + "type": "string", + "nullable": true }, - "startIndex": { - "type": "number" + "status": { + "type": "integer" }, - "Resources": { + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string" - }, - "userName": { - "type": "string" - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } - }, - "emails": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "primary": { - "type": "boolean" - }, - "type": { - "type": "string" - } - } - } - }, - "groups": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } - } - }, - "active": { - "type": "boolean" - }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } - } - } - }, - "required": [ - "schemas", - "id" - ] + "type": "string" } } - }, - "required": [ - "schemas", - "totalResults", - "itemsPerPage", - "startIndex", - "Resources" - ] - }, - "examples": { - "default": { - "value": { - "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" - } - } - ] - } } } } @@ -334421,16 +338644,16 @@ "subcategory": "scim" } }, - "post": { - "summary": "Provision and invite a SCIM enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nProvision enterprise membership for a user, and send organization invitation emails to the email address.\n\nYou 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.", - "operationId": "enterprise-admin/provision-and-invite-enterprise-user", + "patch": { + "summary": "Update an attribute for a SCIM enterprise user", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nUpdate a provisioned user's individual attributes.\n\nTo 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).\n\n**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.\n\n**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.\n```\n{\n \"Operations\":[{\n \"op\":\"replace\",\n \"value\":{\n \"active\":false\n }\n }]\n}\n```", + "operationId": "enterprise-admin/update-attribute-for-enterprise-user", "tags": [ "enterprise-admin" ], "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#provision-and-invite-a-scim-enterprise-user" + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-user" }, "parameters": [ { @@ -334441,6 +338664,15 @@ "schema": { "type": "string" } + }, + { + "name": "scim_user_id", + "description": "The unique identifier of the SCIM user.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } } ], "requestBody": { @@ -334449,102 +338681,101 @@ "application/json": { "schema": { "type": "object", + "required": [ + "Operations", + "schemas" + ], "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "userName": { - "type": "string", - "description": "The username for the user." - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string", - "description": "The first name of the user." - }, - "familyName": { - "type": "string", - "description": "The last name of the user." - } - }, - "required": [ - "givenName", - "familyName" - ] - }, - "emails": { + "Operations": { "type": "array", - "description": "List of user emails.", + "description": "patch operations list", "items": { "type": "object", + "required": [ + "op" + ], "properties": { - "value": { + "op": { "type": "string", - "description": "The email address." + "enum": [ + "add", + "replace", + "remove" + ] }, - "type": { - "type": "string", - "description": "The type of email address." + "path": { + "type": "string" }, - "primary": { - "type": "boolean", - "description": "Whether this email address is the primary address." + "value": { + "type": "string", + "description": "Corresponding 'value' of that field specified by 'path'" } - }, - "required": [ - "value", - "type", - "primary" - ] + } } }, - "groups": { + "schemas": { "type": "array", - "description": "List of SCIM group IDs the user is a member of.", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:PatchOp" + ] } } - }, - "required": [ - "schemas", - "userName", - "name", - "emails" - ] + } }, "examples": { - "default": { + "userMultiValuedProperties": { + "summary": "Multi Valued Property", "value": { "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" + "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], - "userName": "mona.octocat@okta.example.com", - "name": { - "familyName": "Octocat", - "givenName": "Mona" - }, - "emails": [ + "Operations": [ { - "value": "mona.octocat@okta.example.com", - "type": "work", - "primary": true + "op": "replace", + "path": "emails[type eq 'work'].value", + "value": "updatedEmail@microsoft.com" + }, + { + "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": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com" + }, + { + "op": "replace", + "path": "displayName", + "value": "Monalisa Octocat" } + ] + } + }, + "disableUser": { + "summary": "Disable User", + "value": { + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], - "groups": [ + "Operations": [ { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "op": "replace", + "path": "active", + "value": false } ] } @@ -334554,566 +338785,557 @@ } }, "responses": { - "201": { - "description": "Response", + "200": { + "description": "Success, user was updated", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string" - }, - "userName": { - "type": "string" - }, - "name": { + "allOf": [ + { "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } - }, - "emails": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "type": { - "type": "string" + "schemas": { + "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] }, - "primary": { - "type": "boolean" + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true + }, + "userName": { + "type": "string", + "description": "The username for the user.", + "example": "E012345" + }, + "name": { + "type": "object", + "required": [ + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } } - } - } - }, - "groups": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "roles": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } } } } }, - "active": { - "type": "boolean" - }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." }, - "location": { - "type": "string" + "meta": { + "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], + "properties": { + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" + }, + "created": { + "type": "string", + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" + }, + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" + }, + "location": { + "type": "string", + "description": "A URL location of an object" + } + } } } } - }, - "required": [ - "schemas", - "id" ] }, "examples": { - "default": { + "userMultiValuedProperties": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], - "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc", - "externalId": "00dowz5dr9oSfDFRA0h7", - "userName": "mona.octocat@okta.example.com", + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", "givenName": "Mona", - "familyName": "Octocat" + "middleName": "Lisa" }, + "displayName": "Mona Lisa", "emails": [ { - "value": "mona.octocat@okta.example.com", + "value": "mlisa@example.com", "type": "work", "primary": true } ], - "groups": [ + "roles": [ { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "value": "User", + "primary": false } ], - "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" } } - } - } - } - } - } - }, - "x-github": { - "enabledForGitHubApps": true, - "githubCloudOnly": false, - "category": "enterprise-admin", - "subcategory": "scim" - } - } - }, - "/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}": { - "get": { - "summary": "Get SCIM provisioning information for an enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", - "operationId": "enterprise-admin/get-provisioning-information-for-enterprise-user", - "tags": [ - "enterprise-admin" - ], - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#get-scim-provisioning-information-for-an-enterprise-user" - }, - "parameters": [ - { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "scim_user_id", - "description": "The unique identifier of the SCIM user.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Response", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string" - }, - "userName": { - "type": "string" - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } - }, - "emails": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "type": { - "type": "string" - }, - "primary": { - "type": "boolean" - } - } - } - }, - "groups": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } + }, + "userSingleValuedProperties": { + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true } - } - }, - "active": { - "type": "boolean" - }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" + ], + "roles": [ + { + "value": "User", + "primary": false } + ], + "meta": { + "resourceType": "User", + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" } } }, - "required": [ - "schemas", - "id" - ] - }, - "examples": { - "default": { + "disableUser": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], - "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc", - "externalId": "00dowz5dr9oSfDFRA0h7", - "userName": "mona.octocat@okta.example.com", + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", "givenName": "Mona", - "familyName": "Octocat" + "middleName": "Lisa" }, + "displayName": "Mona Lisa", "emails": [ { - "value": "mona.octocat@okta.example.com", + "value": "mlisa@example.com", "type": "work", "primary": true } ], - "groups": [ + "roles": [ { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "value": "User", + "primary": false } ], - "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" } } } } } } - } - }, - "x-github": { - "enabledForGitHubApps": true, - "githubCloudOnly": false, - "category": "enterprise-admin", - "subcategory": "scim" - } - }, - "put": { - "summary": "Set SCIM information for a provisioned enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nReplaces 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-an-enterprise-scim-user) endpoint instead.\n\nYou must at least provide the required values for the user: `userName`, `name`, and `emails`.\n\n**Warning:** Setting `active: false` removes the user from the enterprise, deletes the external identity, and deletes the associated `{scim_user_id}`.", - "operationId": "enterprise-admin/set-information-for-provisioned-enterprise-user", - "tags": [ - "enterprise-admin" - ], - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-user" - }, - "parameters": [ - { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } }, - { - "name": "scim_user_id", - "description": "The unique identifier of the SCIM user.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "userName": { - "type": "string", - "description": "The username for the user." - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string", - "description": "The first name of the user." - }, - "familyName": { - "type": "string", - "description": "The last name of the user." - } + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "required": [ - "givenName", - "familyName" - ] - }, - "emails": { - "type": "array", - "description": "List of user emails.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The email address." - }, - "type": { - "type": "string", - "description": "The type of email address." - }, - "primary": { - "type": "boolean", - "description": "Whether this email address is the primary address." - } - }, - "required": [ - "value", - "type", - "primary" - ] - } - }, - "groups": { - "type": "array", - "description": "List of SCIM group IDs the user is a member of.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } } - }, - "required": [ - "schemas", - "userName", - "name", - "emails" - ] + } }, - "examples": { - "default": { - "value": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "userName": "mona.octocat@okta.example.com", - "name": { - "familyName": "Octocat", - "givenName": "Mona" + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "emails": [ - { - "value": "mona.octocat@okta.example.com", - "type": "work", - "primary": true - } - ], - "groups": [ - { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } - ] + } } } } } - } - }, - "responses": { - "200": { - "description": "Response", + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", "content": { "application/json": { "schema": { + "title": "Basic Error", + "description": "Basic Error", "type": "object", "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } + "message": { + "type": "string" }, - "id": { + "documentation_url": { "type": "string" }, - "externalId": { + "url": { "type": "string" }, - "userName": { + "status": { "type": "string" + } + } + } + } + } + }, + "409": { + "description": "Duplicate record detected" + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } + "documentation_url": { + "type": "string", + "nullable": true }, - "emails": { + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "type": { - "type": "string" - }, - "primary": { - "type": "boolean" - } - } + "type": "string" } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "groups": { + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } + "type": "string" } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "active": { - "type": "boolean" + "documentation_url": { + "type": "string", + "nullable": true }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } - }, - "required": [ - "schemas", - "id" - ] - }, - "examples": { - "default": { - "value": { - "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" + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } } @@ -335129,16 +339351,16 @@ "subcategory": "scim" } }, - "patch": { - "summary": "Update an attribute for a SCIM enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nAllows 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](https://tools.ietf.org/html/rfc7644#section-3.5.2).\n\n**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.\n\n**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`.\n\n```\n{\n \"Operations\":[{\n \"op\":\"replace\",\n \"value\":{\n \"active\":false\n }\n }]\n}\n```", - "operationId": "enterprise-admin/update-attribute-for-enterprise-user", + "delete": { + "summary": "Delete a SCIM user from an enterprise", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nPermanently suspends a SCIM user from an enterprise, removes all data for the user, obfuscates the login, email, and display name of the user, removes all external-identity SCIM attributes, and deletes the emails, avatar, PATs, SSH keys, OAuth authorizations credentials, GPG keys, and SAML mappings for the user. You will not be able to undo this action.", + "operationId": "enterprise-admin/delete-user-from-enterprise", "tags": [ "enterprise-admin" ], "externalDocs": { "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-user" + "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-user-from-an-enterprise" }, "parameters": [ { @@ -335160,185 +339382,254 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "Operations": { - "type": "array", - "description": "Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2).", - "items": { - "type": "object" + "responses": { + "204": { + "description": "User was deleted, no content" + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" + } } } - }, - "required": [ - "schemas", - "Operations" - ] + } }, - "examples": { - "default": { - "value": { - "schemas": [ - "urn:ietf:params:scim:api:messages:2.0:PatchOp" - ], - "Operations": [ - { - "op": "add", - "path": "emails", - "value": [ - { - "value": "monalisa@octocat.github.com", - "type": "home" - } - ] - }, - { - "op": "replace", - "path": "name.givenName", - "value": "Monalisa" + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } - ] + } } } } } - } - }, - "responses": { - "200": { - "description": "Response", + }, + "401": { + "description": "Authorization failure" + }, + "403": { + "description": "Permission denied" + }, + "404": { + "description": "Resource not found", "content": { "application/json": { "schema": { + "title": "Basic Error", + "description": "Basic Error", "type": "object", "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } + "message": { + "type": "string" }, - "id": { + "documentation_url": { "type": "string" }, - "externalId": { + "url": { "type": "string" }, - "userName": { + "status": { "type": "string" + } + } + } + } + } + }, + "429": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } + "documentation_url": { + "type": "string", + "nullable": true }, - "emails": { + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "type": { - "type": "string" - }, - "primary": { - "type": "boolean" - } - } + "type": "string" } + } + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "groups": { + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { "type": "array", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } + "type": "string" } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true }, - "active": { - "type": "boolean" + "documentation_url": { + "type": "string", + "nullable": true }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } - }, - "required": [ - "schemas", - "id" - ] - }, - "examples": { - "default": { - "value": { - "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" + } + } + }, + "application/scim+json": { + "schema": { + "title": "Scim Error", + "description": "Scim Error", + "type": "object", + "properties": { + "message": { + "type": "string", + "nullable": true + }, + "documentation_url": { + "type": "string", + "nullable": true + }, + "detail": { + "type": "string", + "nullable": true + }, + "status": { + "type": "integer" + }, + "scimType": { + "type": "string", + "nullable": true + }, + "schemas": { + "type": "array", + "items": { + "type": "string" } } } @@ -335353,49 +339644,6 @@ "category": "enterprise-admin", "subcategory": "scim" } - }, - "delete": { - "summary": "Delete a SCIM user from an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", - "operationId": "enterprise-admin/delete-user-from-enterprise", - "tags": [ - "enterprise-admin" - ], - "externalDocs": { - "description": "API method documentation", - "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-user-from-an-enterprise" - }, - "parameters": [ - { - "name": "enterprise", - "description": "The slug version of the enterprise name. You can also substitute this value with the enterprise id.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "scim_user_id", - "description": "The unique identifier of the SCIM user.", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "204": { - "description": "Response" - } - }, - "x-github": { - "enabledForGitHubApps": true, - "githubCloudOnly": false, - "category": "enterprise-admin", - "subcategory": "scim" - } } }, "/search/code": { @@ -373762,6 +378010,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.yaml b/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.yaml index 4af9bccfde..a2f6a34330 100644 --- a/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.yaml +++ b/descriptions/ghes-3.6/dereferenced/ghes-3.6.deref.yaml @@ -3534,7 +3534,7 @@ paths: application/json: schema: *29 application/scim+json: - schema: + schema: &422 title: Scim Error description: Scim Error type: object @@ -12930,7 +12930,7 @@ paths: url: type: string format: uri - user: &446 + user: &459 title: Public User description: Public User type: object @@ -16522,7 +16522,7 @@ paths: type: array items: *67 examples: - default: &456 + default: &469 value: - login: github id: 1 @@ -17335,7 +17335,7 @@ paths: type: array items: *81 examples: - default: &452 + default: &465 value: total_count: 1 repositories: @@ -22513,7 +22513,7 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/migrations#get-an-organization-migration-status parameters: - *112 - - &455 + - &468 name: migration_id description: The unique identifier of the migration. in: path @@ -23721,7 +23721,7 @@ paths: application/json: schema: *81 examples: - default: &458 + default: &471 value: id: 1296269 node_id: MDEwOlJlcG9zaXRvcnkxMjk2MjY5 @@ -24817,7 +24817,7 @@ paths: - updated_at - url examples: - default: &436 + default: &449 value: - author: login: octocat @@ -25056,7 +25056,7 @@ paths: application/json: schema: *187 examples: - default: &437 + default: &450 value: author: login: octocat @@ -25233,7 +25233,7 @@ paths: - updated_at - url examples: - default: &438 + default: &451 value: - author: login: octocat @@ -25450,7 +25450,7 @@ paths: application/json: schema: *190 examples: - default: &439 + default: &452 value: author: login: octocat @@ -26101,7 +26101,7 @@ paths: - state - url examples: - response-if-user-is-a-team-maintainer: &440 + response-if-user-is-a-team-maintainer: &453 summary: Response if user is a team maintainer value: url: https://api.github.com/teams/1/memberships/octocat @@ -26164,7 +26164,7 @@ paths: application/json: schema: *201 examples: - response-if-users-membership-with-team-is-now-pending: &441 + response-if-users-membership-with-team-is-now-pending: &454 summary: Response if user's membership with team is now pending value: url: https://api.github.com/teams/1/memberships/octocat @@ -26303,7 +26303,7 @@ paths: - updated_at - permissions examples: - default: &442 + default: &455 value: - owner_url: https://api.github.com/orgs/octocat url: https://api.github.com/projects/1002605 @@ -26379,7 +26379,7 @@ paths: application/json: schema: *202 examples: - default: &443 + default: &456 value: owner_url: https://api.github.com/orgs/octocat url: https://api.github.com/projects/1002605 @@ -26576,7 +26576,7 @@ paths: description: Alternative response with repository permissions content: application/json: - schema: &444 + schema: &457 title: Team Repository description: A team's access to a repository. type: object @@ -27354,7 +27354,7 @@ paths: type: array items: *209 examples: - response-if-child-teams-exist: &445 + response-if-child-teams-exist: &458 value: - id: 2 node_id: MDQ6VGVhbTI= @@ -47818,6 +47818,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -49872,7 +49878,7 @@ paths: type: array items: *343 examples: - default: &459 + default: &472 value: - id: 1 repository: @@ -59144,12 +59150,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -63788,6 +63798,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -65100,8 +65115,12 @@ paths: "/scim/v2/enterprises/{enterprise}/Groups": get: summary: List provisioned SCIM groups for an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/list-provisioned-groups-enterprise tags: - enterprise-admin @@ -65109,149 +65128,248 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#list-provisioned-scim-groups-for-an-enterprise parameters: - - *62 - - &425 - name: startIndex - description: 'Used for pagination: the index of the first result to return.' + - 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: integer - - &426 - name: count - description: 'Used for pagination: the number of results to return.' + type: string + examples: + displayName: + value: Engineering + externalId: + value: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + - &433 + name: excludedAttributes + description: Excludes the specified attribute from being returned in the results. + Using this parameter can speed up response time. in: query required: false schema: - type: integer - - name: filter - description: filter results + type: string + example: members + - &434 + name: startIndex + description: 'Used for pagination: the starting index of the first result + to return when paginating through values.' in: query required: false schema: - type: string - - name: excludedAttributes - description: attributes to exclude + type: integer + default: 1 + format: int32 + example: 1 + - &435 + name: count + description: 'Used for pagination: the number of results to return per page.' in: query required: false schema: - type: string + type: integer + default: 30 + format: int32 + example: 1 + - *62 responses: '200': - description: Response + description: Success, either groups were found or not found content: application/json: schema: type: object + required: + - schemas + - totalResults + - Resources + - startIndex + - itemsPerPage properties: schemas: type: array + description: The URIs that are used to indicate the namespaces + of the list SCIM schemas. items: type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: - type: number - itemsPerPage: - type: number - startIndex: - type: number + type: integer + description: Number of results found + example: 1 Resources: type: array - items: - type: object - properties: - schemas: - type: array - items: + description: Information about each provisioned group. + items: &424 + allOf: + - &423 + type: object + required: + - schemas + - externalId + - displayName + - members + properties: + schemas: + type: array + description: The URIs that are used to indicate the namespaces + of the SCIM schemas. + items: + type: string + enum: + - urn:ietf:params:scim:schemas:core:2.0:Group + example: + - urn:ietf:params:scim:schemas:core:2.0:Group + externalId: type: string - id: - type: string - externalId: - type: string - nullable: true - displayName: - type: string - members: - type: array - items: + description: A unique identifier for the resource as defined + by the provisioning client. + example: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + displayName: + type: string + description: A human-readable name for a security group. + example: Engineering + members: + type: array + description: The group members. + items: + type: object + required: + - value + - displayName + properties: + value: + type: string + description: The local unique identifier for the + member + example: 23a35c27-23d3-4c03-b4c5-6443c09e7173 + displayName: + type: string + description: The display name associated with the + member + example: Monalisa Octocat + - type: object + required: + - id + - meta + - members + properties: + id: + type: string + description: The internally generated id for the group + object. + example: 7fce0092-d52e-4f76-b727-3955bd72c939 + members: + type: array + description: The security group members. + example: + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 + meta: &436 type: object + description: The metadata associated with the creation/updates + to the user. + required: + - resourceType properties: - value: + resourceType: type: string - "$ref": + description: A type of a resource + enum: + - User + - Group + example: User + created: type: string - display: + description: A date and time when the user was created. + example: '2022-03-27T19:59:26.000Z' + lastModified: type: string - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id - required: - - schemas - - totalResults - - itemsPerPage - - startIndex - - Resources + description: A data and time when the user was last + modified. + example: '2022-03-27T19:59:26.000Z' + location: + type: string + description: A URL location of an object + startIndex: + type: integer + description: A starting index for the returned page + example: 1 + itemsPerPage: + type: integer + description: Number of objects per page + example: 20 examples: default: value: schemas: - urn:ietf:params:scim:api:messages:2.0:ListResponse - totalResults: 2 - itemsPerPage: 2 - startIndex: 1 + totalResults: 1 Resources: - schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - displayName: octo-org + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + id: 927fa2c08dcb4a7fae9e + displayName: Engineering 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 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 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: - 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e + startIndex: 1 + itemsPerPage: 20 + '400': &425 + description: Bad request + content: + application/json: + schema: *422 + application/scim+json: + schema: *422 + '401': &426 + description: Authorization failure + '403': &427 + description: Permission denied + '429': &428 + description: Too many requests + content: + application/json: + schema: *422 + application/scim+json: + schema: *422 + '500': &429 + description: Internal server error + content: + application/json: + schema: *422 + application/scim+json: + schema: *422 x-github: enabledForGitHubApps: true githubCloudOnly: false category: enterprise-admin subcategory: scim post: - summary: Provision a SCIM enterprise group and invite users + summary: Provision a SCIM enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - 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. + 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: enterprise-admin/provision-and-invite-enterprise-group tags: - enterprise-admin @@ -65264,104 +65382,47 @@ paths: required: true content: application/json: - schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - displayName: - type: string - description: The name of the SCIM group. This must match the GitHub - organization that the group maps to. - members: - type: array - items: - type: object - properties: - value: - type: string - description: The SCIM user ID for a user. - required: - - value - required: - - schemas - - displayName + schema: *423 examples: - default: + group: value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - displayName: octo-org - members: - - value: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - - value: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + displayName: Engineering responses: '201': - description: Response + description: Group has been created content: application/json: - schema: &422 - type: object - properties: - schemas: - type: array - items: - type: string - id: - type: string - externalId: - type: string - nullable: true - displayName: - type: string - members: - type: array - items: - type: object - properties: - value: - type: string - "$ref": - type: string - display: - type: string - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id + schema: *424 examples: - default: &423 + group: &430 value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - displayName: octo-org + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + displayName: Engineering 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 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e + '400': *425 + '401': *426 + '403': *427 + '409': &432 + description: Duplicate record detected + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65370,8 +65431,10 @@ paths: "/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}": get: summary: Get SCIM provisioning information for an enterprise group - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/get-provisioning-information-for-enterprise-group tags: - enterprise-admin @@ -65380,27 +65443,28 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#get-scim-provisioning-information-for-an-enterprise-group parameters: - *62 - - &424 + - &431 name: scim_group_id - description: Identifier generated by the GitHub SCIM endpoint. + description: A unique identifier of the SCIM group. in: path required: true schema: type: string - - name: excludedAttributes - description: Attributes to exclude. - in: query - required: false - schema: - type: string + example: 7fce0092-d52e-4f76-b727-3955bd72c939 responses: '200': - description: Response + description: Success, a group was found content: application/json: - schema: *422 + schema: *424 examples: - default: *423 + default: *430 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65409,9 +65473,11 @@ paths: put: summary: Set SCIM information for a provisioned enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - 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. + 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: enterprise-admin/set-information-for-provisioned-enterprise-group tags: - enterprise-admin @@ -65420,53 +65486,48 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-group parameters: - *62 - - *424 + - *431 requestBody: required: true content: application/json: - schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - displayName: - type: string - description: The name of the SCIM group. This must match the GitHub - organization that the group maps to. - members: - type: array - items: - type: object - properties: - value: - type: string - description: The SCIM user ID for a user. - required: - - value - required: - - schemas - - displayName + schema: *423 examples: - default: + group: + summary: Group value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - displayName: octo-org + 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: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - - value: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 responses: '200': - description: Response + description: Group was updated content: application/json: - schema: *422 + schema: *424 examples: - default: *423 + group: *430 + groupWithMembers: *430 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '409': *432 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65475,9 +65536,13 @@ paths: patch: summary: Update an attribute for a SCIM enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - 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](https://tools.ietf.org/html/rfc7644#section-3.5.2). + 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: enterprise-admin/update-attribute-for-enterprise-group tags: - enterprise-admin @@ -65486,77 +65551,80 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-group parameters: - *62 - - *424 + - *431 requestBody: required: true content: application/json: - schema: + schema: &442 type: object + required: + - Operations + - schemas properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string Operations: type: array - description: Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2). - minItems: 1 + description: patch operations list items: type: object + required: + - op properties: op: type: string enum: - add - - Add - - remove - - Remove - replace - - Replace + - remove path: type: string value: - description: Can be any value - string, number, array or object. - required: - - op - required: - - schemas - - Operations + type: string + description: Corresponding 'value' of that field specified + by 'path' + schemas: + type: array + items: + type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:PatchOp examples: - default: + 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: remove + - op: add path: members value: - - value: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 responses: '200': - description: Response + description: Success, group was updated content: application/json: - schema: *422 + schema: *424 examples: - default: - value: - schemas: - - urn:ietf:params:scim:schemas:core:2.0:Group - id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - 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 + updateGroup: *430 + addMembers: *430 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '409': *432 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65564,8 +65632,10 @@ paths: subcategory: scim delete: summary: Delete a SCIM group from an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/delete-scim-group-from-enterprise tags: - enterprise-admin @@ -65574,10 +65644,16 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-group-from-an-enterprise parameters: - *62 - - *424 + - *431 responses: '204': - description: Response + description: Group was deleted, no content + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65587,24 +65663,13 @@ paths: get: summary: List SCIM provisioned identities for an enterprise description: |- - **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 Enterprise Server. 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. + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change. - 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 Enterprise Server account after completing SSO: + Lists provisioned SCIM enterprise members. - 1. The user is granted access by the IdP and is not a member of the GitHub Enterprise Server enterprise. + 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. - 1. The user attempts to access the GitHub Enterprise Server enterprise and initiates the SAML SSO process, and is not currently signed in to their GitHub Enterprise Server account. - - 1. 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 Enterprise Server account: - - If the user signs in, their GitHub Enterprise Server 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 Server enterprise, and the external identity `null` entry remains in place. + You can improve query search time by using the `excludedAttributes` query parameter with a value of `groups` to exclude groups from the response. operationId: enterprise-admin/list-provisioned-identities-enterprise tags: - enterprise-admin @@ -65612,156 +65677,233 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#list-scim-provisioned-identities-for-an-enterprise parameters: - - *62 - - *425 - - *426 - name: filter - description: filter results + 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' + - *433 + - *434 + - *435 + - *62 responses: '200': - description: Response + description: Success, either users were found or not found content: application/json: schema: type: object + required: + - schemas + - totalResults + - Resources + - startIndex + - itemsPerPage properties: schemas: type: array + description: The URIs that are used to indicate the namespaces + of the list SCIM schemas. items: type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: - type: number - itemsPerPage: - type: number - startIndex: - type: number + type: integer + description: Number of results found + example: 1 Resources: type: array - items: - type: object - properties: - schemas: - type: array - items: - type: string - id: - type: string - externalId: - type: string - userName: - type: string - name: - type: object - properties: - givenName: - type: string - familyName: + description: Information about each provisioned account. + items: &438 + allOf: + - &437 + type: object + required: + - schemas + - externalId + - userName + - active + - displayName + - emails + properties: + schemas: + type: array + description: The URIs that are used to indicate the namespaces + of the SCIM schemas. + items: type: string - emails: - type: array - items: + enum: + - urn:ietf:params:scim:schemas:core:2.0:User + example: + - urn:ietf:params:scim:schemas:core:2.0:User + externalId: + type: string + description: A unique identifier for the resource as defined + by the provisioning client. + example: E012345 + active: + type: boolean + description: Whether the user active in the IdP. + example: true + userName: + type: string + description: The username for the user. + example: E012345 + name: type: object + required: + - familyName + - givenName properties: - value: + formatted: type: string - primary: - type: boolean - type: + description: The full name, including all middle names, + titles, and suffixes as appropriate, formatted for + display. + example: Ms. Mona Lisa Octocat + familyName: type: string - groups: - type: array - items: - type: object - properties: - value: + description: The family name of the user. + example: Octocat + givenName: type: string - active: - type: boolean - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id - required: - - schemas - - totalResults - - itemsPerPage - - startIndex - - Resources + description: The given name of the user. + example: Mona + middleName: + type: string + description: The middle name(s) of the user. + example: Lisa + displayName: + type: string + description: A human-readable name for the user. + example: Mona Lisa + emails: + type: array + description: The emails for the user. + items: + type: object + required: + - value + - type + - primary + properties: + value: + type: string + description: The email address. + example: mlisa@example.com + type: + type: string + description: The type of email address. + example: work + primary: + type: boolean + description: Whether this email address is the primary + address. + example: true + roles: + type: array + description: The roles assigned to the user. + items: + type: object + required: + - value + properties: + value: + type: string + description: The role value representing a user + role in GitHub. + enum: + - User + - Enterprise Owner + example: User + primary: + type: boolean + description: Is the role a primary role for the + user. + example: false + - type: object + required: + - id + - meta + properties: + id: + type: string + description: The internally generated id for the user + object. + example: 7fce0092-d52e-4f76-b727-3955bd72c939 + groups: + type: array + description: Provisioned SCIM groups that the user is + a member of. + meta: *436 + startIndex: + type: integer + description: A starting index for the returned page + example: 1 + itemsPerPage: + type: integer + description: Number of objects per page + example: 20 examples: default: value: schemas: - urn:ietf:params:scim:api:messages:2.0:ListResponse - totalResults: 2 - itemsPerPage: 2 - startIndex: 1 + totalResults: 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 + externalId: E012345 + id: 7fce0092-d52e-4f76-b727-3955bd72c939 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 + userName: E012345 name: - givenName: hu - familyName: bot + formatted: Ms. Mona Lisa Octocat + familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: hubot@example.com + - value: mlisa@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 + roles: + - value: User + primary: false + startIndex: 1 + itemsPerPage: 20 + '400': *425 + '401': *426 + '403': *427 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false category: enterprise-admin subcategory: scim post: - summary: Provision and invite a SCIM enterprise user + summary: Provision a SCIM enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - Provision enterprise membership for a user, and send organization invitation emails to the email address. + 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`. - 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. + 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: enterprise-admin/provision-and-invite-enterprise-user tags: - enterprise-admin @@ -65774,158 +65916,90 @@ paths: required: true content: application/json: - schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - userName: - type: string - description: The username for the user. - name: - type: object - properties: - givenName: - type: string - description: The first name of the user. - familyName: - type: string - description: The last name of the user. - required: - - givenName - - familyName - emails: - type: array - description: List of user emails. - items: - type: object - properties: - value: - type: string - description: The email address. - type: - type: string - description: The type of email address. - primary: - type: boolean - description: Whether this email address is the primary address. - required: - - value - - type - - primary - groups: - type: array - description: List of SCIM group IDs the user is a member of. - items: - type: object - properties: - value: - type: string - required: - - schemas - - userName - - name - - emails + schema: *437 examples: - default: + user: &441 + summary: User value: schemas: - urn:ietf:params:scim:schemas:core:2.0:User - userName: mona.octocat@okta.example.com + externalId: E012345 + active: true + userName: E012345 name: + formatted: Ms. Mona Lisa Octocat familyName: Octocat givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: mona.octocat@okta.example.com + - value: mlisa@example.com type: work primary: true - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d + roles: + - value: User + primary: false + enterpriseOwner: + summary: Enterprise Owner + value: + schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + externalId: E012345 + active: true + userName: E012345 + name: + formatted: Ms. Mona Lisa Octocat + familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa + emails: + - value: mlisa@example.com + type: work + primary: true + roles: + - value: Enterprise Owner + primary: false responses: '201': - description: Response + description: User has been created content: application/json: - schema: &427 - type: object - properties: - schemas: - type: array - items: - type: string - id: - type: string - externalId: - type: string - userName: - type: string - name: - type: object - properties: - givenName: - type: string - familyName: - type: string - emails: - type: array - items: - type: object - properties: - value: - type: string - type: - type: string - primary: - type: boolean - groups: - type: array - items: - type: object - properties: - value: - type: string - active: - type: boolean - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id + schema: *438 examples: - default: &428 + user: &439 value: schemas: - urn:ietf:params:scim:schemas:core:2.0:User - id: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - externalId: 00dowz5dr9oSfDFRA0h7 - userName: mona.octocat@okta.example.com + id: 7fce0092-d52e-4f76-b727-3955bd72c939 + externalId: E012345 + active: true + userName: E012345 name: - givenName: Mona + formatted: Ms. Mona Lisa Octocat familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: mona.octocat@okta.example.com + - value: mlisa@example.com type: work primary: true - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d - active: true + roles: + - value: User + primary: false 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939 + enterpriseOwner: *439 + '400': *425 + '401': *426 + '403': *427 + '409': *432 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65934,8 +66008,10 @@ paths: "/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}": get: summary: Get SCIM provisioning information for an enterprise user - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/get-provisioning-information-for-enterprise-user tags: - enterprise-admin @@ -65944,7 +66020,7 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#get-scim-provisioning-information-for-an-enterprise-user parameters: - *62 - - &429 + - &440 name: scim_user_id description: The unique identifier of the SCIM user. in: path @@ -65953,12 +66029,18 @@ paths: type: string responses: '200': - description: Response + description: Success, a user was found content: application/json: - schema: *427 + schema: *438 examples: - default: *428 + default: *439 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -65967,13 +66049,13 @@ paths: put: summary: Set SCIM information for a provisioned enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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-an-enterprise-scim-user) endpoint instead. + Replaces an existing provisioned user's information. - You must at least provide the required values for the user: `userName`, `name`, and `emails`. + 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` removes the user from the enterprise, deletes the external identity, and deletes the associated `{scim_user_id}`. + **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: enterprise-admin/set-information-for-provisioned-enterprise-user tags: - enterprise-admin @@ -65982,89 +66064,29 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#set-scim-information-for-a-provisioned-enterprise-user parameters: - *62 - - *429 + - *440 requestBody: required: true content: application/json: - schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - userName: - type: string - description: The username for the user. - name: - type: object - properties: - givenName: - type: string - description: The first name of the user. - familyName: - type: string - description: The last name of the user. - required: - - givenName - - familyName - emails: - type: array - description: List of user emails. - items: - type: object - properties: - value: - type: string - description: The email address. - type: - type: string - description: The type of email address. - primary: - type: boolean - description: Whether this email address is the primary address. - required: - - value - - type - - primary - groups: - type: array - description: List of SCIM group IDs the user is a member of. - items: - type: object - properties: - value: - type: string - required: - - schemas - - userName - - name - - emails + schema: *437 examples: - default: - value: - schemas: - - urn:ietf:params:scim:schemas:core:2.0:User - userName: mona.octocat@okta.example.com - name: - familyName: Octocat - givenName: Mona - emails: - - value: mona.octocat@okta.example.com - type: work - primary: true - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d + user: *441 responses: '200': - description: Response + description: User was updated content: application/json: - schema: *427 + schema: *438 examples: - default: *428 + user: *439 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '409': *432 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -66073,14 +66095,15 @@ paths: patch: summary: Update an attribute for a SCIM enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* 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](https://tools.ietf.org/html/rfc7644#section-3.5.2). + Update a provisioned user's individual attributes. - **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. + 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). - **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`. + **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":[{ @@ -66099,72 +66122,63 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#update-an-attribute-for-a-scim-enterprise-user parameters: - *62 - - *429 + - *440 requestBody: required: true content: application/json: - schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - Operations: - type: array - description: Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2). - items: - type: object - required: - - schemas - - Operations + schema: *442 examples: - default: + 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: updatedEmail@microsoft.com + - 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: 5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com + - op: replace + path: displayName + value: Monalisa Octocat + disableUser: + summary: Disable User value: schemas: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: - - op: add - path: emails - value: - - value: monalisa@octocat.github.com - type: home - op: replace - path: name.givenName - value: Monalisa + path: active + value: false responses: '200': - description: Response + description: Success, user was updated content: application/json: - schema: *427 + schema: *438 examples: - default: - value: - 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 + userMultiValuedProperties: *439 + userSingleValuedProperties: *439 + disableUser: *439 + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '409': *432 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -66172,8 +66186,10 @@ paths: subcategory: scim delete: summary: Delete a SCIM user from an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + description: |- + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change. + + Permanently suspends a SCIM user from an enterprise, removes all data for the user, obfuscates the login, email, and display name of the user, removes all external-identity SCIM attributes, and deletes the emails, avatar, PATs, SSH keys, OAuth authorizations credentials, GPG keys, and SAML mappings for the user. You will not be able to undo this action. operationId: enterprise-admin/delete-user-from-enterprise tags: - enterprise-admin @@ -66182,10 +66198,16 @@ paths: url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#delete-a-scim-user-from-an-enterprise parameters: - *62 - - *429 + - *440 responses: '204': - description: Response + description: User was deleted, no content + '400': *425 + '401': *426 + '403': *427 + '404': *35 + '429': *428 + '500': *429 x-github: enabledForGitHubApps: true githubCloudOnly: false @@ -66242,7 +66264,7 @@ paths: type: string enum: - indexed - - &430 + - &443 name: order description: Determines whether the first search result returned is the highest number of matches (`desc`) or lowest number of matches (`asc`). This parameter @@ -66313,7 +66335,7 @@ paths: example: - 73..77 - 77..78 - text_matches: &431 + text_matches: &444 title: Search Result Text Matches type: array items: @@ -66476,7 +66498,7 @@ paths: enum: - author-date - committer-date - - *430 + - *443 - *4 - *5 responses: @@ -66592,7 +66614,7 @@ paths: type: number node_id: type: string - text_matches: *431 + text_matches: *444 required: - sha - node_id @@ -66784,7 +66806,7 @@ paths: - interactions - created - updated - - *430 + - *443 - *4 - *5 responses: @@ -66903,7 +66925,7 @@ paths: type: string format: date-time nullable: true - text_matches: *431 + text_matches: *444 pull_request: type: object properties: @@ -67127,7 +67149,7 @@ paths: enum: - created - updated - - *430 + - *443 - *4 - *5 responses: @@ -67171,7 +67193,7 @@ paths: nullable: true score: type: number - text_matches: *431 + text_matches: *444 required: - id - node_id @@ -67257,7 +67279,7 @@ paths: - forks - help-wanted-issues - updated - - *430 + - *443 - *4 - *5 responses: @@ -67494,7 +67516,7 @@ paths: - admin - pull - push - text_matches: *431 + text_matches: *444 temp_clone_token: type: string allow_merge_commit: @@ -67795,7 +67817,7 @@ paths: type: string format: uri nullable: true - text_matches: *431 + text_matches: *444 related: type: array nullable: true @@ -67986,7 +68008,7 @@ paths: - followers - repositories - joined - - *430 + - *443 - *4 - *5 responses: @@ -68089,7 +68111,7 @@ paths: hireable: type: boolean nullable: true - text_matches: *431 + text_matches: *444 blog: type: string nullable: true @@ -68278,7 +68300,7 @@ paths: description: Response content: application/json: - schema: &432 + schema: &445 type: object properties: status: @@ -68298,7 +68320,7 @@ paths: - name - number examples: - default: &433 + default: &446 value: status: scheduled scheduled_time: Tuesday, January 22 at 15:34 -0800 @@ -68342,9 +68364,9 @@ paths: description: Response content: application/json: - schema: *432 + schema: *445 examples: - default: *433 + default: *446 requestBody: required: true content: @@ -68901,7 +68923,7 @@ paths: application/json: schema: type: array - items: &434 + items: &447 type: object properties: key: @@ -68909,7 +68931,7 @@ paths: pretty-print: type: string examples: - default: &435 + default: &448 value: - key: ssh-rsa AAAAB3NzaC1yc2EAAAAB... pretty-print: ssh-rsa 01:14:0f:f2:0f:e2:fe:e8:f4:72:62:af:75:f7:1a:88:3e:04:92:64 @@ -68950,9 +68972,9 @@ paths: application/json: schema: type: array - items: *434 + items: *447 examples: - default: *435 + default: *448 requestBody: required: true content: @@ -69002,9 +69024,9 @@ paths: application/json: schema: type: array - items: *434 + items: *447 examples: - default: *435 + default: *448 requestBody: required: true content: @@ -69300,7 +69322,7 @@ paths: type: array items: *187 examples: - default: *436 + default: *449 headers: Link: *6 x-github: @@ -69443,7 +69465,7 @@ paths: application/json: schema: *187 examples: - default: *437 + default: *450 x-github: githubCloudOnly: false enabledForGitHubApps: true @@ -69506,7 +69528,7 @@ paths: type: array items: *190 examples: - default: *438 + default: *451 headers: Link: *6 x-github: @@ -69639,7 +69661,7 @@ paths: application/json: schema: *190 examples: - default: *439 + default: *452 x-github: githubCloudOnly: false enabledForGitHubApps: true @@ -70084,7 +70106,7 @@ paths: application/json: schema: *201 examples: - response-if-user-is-a-team-maintainer: *440 + response-if-user-is-a-team-maintainer: *453 '404': *35 x-github: githubCloudOnly: false @@ -70143,7 +70165,7 @@ paths: application/json: schema: *201 examples: - response-if-users-membership-with-team-is-now-pending: *441 + response-if-users-membership-with-team-is-now-pending: *454 '403': description: Forbidden if team synchronization is set up '422': @@ -70216,7 +70238,7 @@ paths: type: array items: *202 examples: - default: *442 + default: *455 headers: Link: *6 '404': *35 @@ -70251,7 +70273,7 @@ paths: application/json: schema: *202 examples: - default: *443 + default: *456 '404': description: Not Found if project is not managed by this team x-github: @@ -70415,7 +70437,7 @@ paths: description: Alternative response with extra repository information content: application/json: - schema: *444 + schema: *457 examples: alternative-response-with-extra-repository-information: value: @@ -70770,7 +70792,7 @@ paths: type: array items: *209 examples: - response-if-child-teams-exist: *445 + response-if-child-teams-exist: *458 headers: Link: *6 '404': *35 @@ -70805,7 +70827,7 @@ paths: application/json: schema: oneOf: - - &447 + - &460 title: Private User description: Private User type: object @@ -71004,7 +71026,7 @@ paths: - private_gists - total_private_repos - two_factor_authentication - - *446 + - *459 examples: response-with-public-and-private-profile-information: summary: Response with public and private profile information @@ -71149,7 +71171,7 @@ paths: description: Response content: application/json: - schema: *447 + schema: *460 examples: default: value: @@ -71226,7 +71248,7 @@ paths: application/json: schema: type: array - items: &448 + items: &461 title: Email description: Email type: object @@ -71251,7 +71273,7 @@ paths: - verified - visibility examples: - default: &457 + default: &470 value: - email: octocat@github.com verified: true @@ -71325,7 +71347,7 @@ paths: application/json: schema: type: array - items: *448 + items: *461 examples: default: value: @@ -71577,7 +71599,7 @@ paths: application/json: schema: type: array - items: &449 + items: &462 title: GPG Key description: A unique encryption key type: object @@ -71701,7 +71723,7 @@ paths: - subkeys - revoked examples: - default: &461 + default: &474 value: - id: 3 name: Octocat's GPG Key @@ -71776,9 +71798,9 @@ paths: description: Response content: application/json: - schema: *449 + schema: *462 examples: - default: &450 + default: &463 value: id: 3 name: Octocat's GPG Key @@ -71834,7 +71856,7 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/users#get-a-gpg-key-for-the-authenticated-user parameters: - - &451 + - &464 name: gpg_key_id description: The unique identifier of the GPG key. in: path @@ -71846,9 +71868,9 @@ paths: description: Response content: application/json: - schema: *449 + schema: *462 examples: - default: *450 + default: *463 '404': *35 '304': *40 '403': *37 @@ -71870,7 +71892,7 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/users#delete-a-gpg-key-for-the-authenticated-user parameters: - - *451 + - *464 responses: '204': description: Response @@ -72065,7 +72087,7 @@ paths: type: array items: *81 examples: - default: *452 + default: *465 headers: Link: *6 '404': *35 @@ -72232,7 +72254,7 @@ paths: application/json: schema: type: array - items: &453 + items: &466 title: Key description: Key type: object @@ -72322,9 +72344,9 @@ paths: description: Response content: application/json: - schema: *453 + schema: *466 examples: - default: &454 + default: &467 value: key: 2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvv1234 id: 2 @@ -72362,9 +72384,9 @@ paths: description: Response content: application/json: - schema: *453 + schema: *466 examples: - default: *454 + default: *467 '404': *35 '304': *40 '403': *37 @@ -73129,7 +73151,7 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/migrations#download-a-user-migration-archive parameters: - - *455 + - *468 responses: '302': description: Response @@ -73152,7 +73174,7 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/migrations#list-repositories-for-a-user-migration parameters: - - *455 + - *468 - *4 - *5 responses: @@ -73200,7 +73222,7 @@ paths: type: array items: *67 examples: - default: *456 + default: *469 headers: Link: *6 '304': *40 @@ -73321,9 +73343,9 @@ paths: application/json: schema: type: array - items: *448 + items: *461 examples: - default: *457 + default: *470 headers: Link: *6 '304': *40 @@ -73420,7 +73442,7 @@ paths: type: array items: *81 examples: - default: &460 + default: &473 summary: Default response value: - id: 1296269 @@ -73705,6 +73727,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response @@ -73712,7 +73742,7 @@ paths: application/json: schema: *81 examples: - default: *458 + default: *471 headers: Location: example: https://api.github.com/repos/octocat/Hello-World @@ -73752,7 +73782,7 @@ paths: type: array items: *343 examples: - default: *459 + default: *472 headers: Link: *6 '304': *40 @@ -73838,11 +73868,11 @@ paths: type: array items: *81 examples: - default-response: *460 + default-response: *473 application/vnd.github.v3.star+json: schema: type: array - items: &462 + items: &475 title: Starred Repository description: Starred Repository type: object @@ -74247,8 +74277,8 @@ paths: application/json: schema: oneOf: - - *447 - - *446 + - *460 + - *459 examples: default-response: summary: Default response @@ -74719,9 +74749,9 @@ paths: application/json: schema: type: array - items: *449 + items: *462 examples: - default: *461 + default: *474 headers: Link: *6 x-github: @@ -74906,7 +74936,7 @@ paths: type: array items: *67 examples: - default: *456 + default: *469 headers: Link: *6 x-github: @@ -75297,11 +75327,11 @@ paths: schema: anyOf: - type: array - items: *462 + items: *475 - type: array items: *81 examples: - default-response: *460 + default-response: *473 headers: Link: *6 x-github: diff --git a/descriptions/ghes-3.6/ghes-3.6.json b/descriptions/ghes-3.6/ghes-3.6.json index 2991b65f9a..23dfdec071 100644 --- a/descriptions/ghes-3.6/ghes-3.6.json +++ b/descriptions/ghes-3.6/ghes-3.6.json @@ -32019,6 +32019,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -40413,7 +40422,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -40421,6 +40430,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -43699,6 +43716,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -44839,7 +44864,7 @@ "/scim/v2/enterprises/{enterprise}/Groups": { "get": { "summary": "List provisioned SCIM groups for an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nLists provisioned SCIM groups in an enterprise.\n\nYou can improve query search time by using the `excludedAttributes` query parameter with a value of `members` to exclude members from the response.", "operationId": "enterprise-admin/list-provisioned-groups-enterprise", "tags": [ "enterprise-admin" @@ -44849,41 +44874,43 @@ "url": "https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#list-provisioned-scim-groups-for-an-enterprise" }, "parameters": [ - { - "$ref": "#/components/parameters/enterprise" - }, - { - "$ref": "#/components/parameters/start-index" - }, - { - "$ref": "#/components/parameters/count" - }, { "name": "filter", - "description": "filter results", + "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" + } } }, { - "name": "excludedAttributes", - "description": "attributes to exclude", - "in": "query", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/excluded-attributes" + }, + { + "$ref": "#/components/parameters/start-index" + }, + { + "$ref": "#/components/parameters/count" + }, + { + "$ref": "#/components/parameters/enterprise" } ], "responses": { "200": { - "description": "Response", + "description": "Success, either groups were found or not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/scim-group-list-enterprise" + "$ref": "#/components/schemas/scim-enterprise-group-list" }, "examples": { "default": { @@ -44892,6 +44919,21 @@ } } } + }, + "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": { @@ -44902,8 +44944,8 @@ } }, "post": { - "summary": "Provision a SCIM enterprise group and invite users", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nProvision 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.", + "summary": "Provision a SCIM enterprise group", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nCreates a SCIM group for an enterprise.\n\nIf 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": "enterprise-admin/provision-and-invite-enterprise-group", "tags": [ "enterprise-admin" @@ -44922,55 +44964,16 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "displayName": { - "type": "string", - "description": "The name of the SCIM group. This must match the GitHub organization that the group maps to." - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The SCIM user ID for a user." - } - }, - "required": [ - "value" - ] - } - } - }, - "required": [ - "schemas", - "displayName" - ] + "$ref": "#/components/schemas/group" }, "examples": { - "default": { + "group": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "displayName": "octo-org", - "members": [ - { - "value": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc" - }, - { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" - } - ] + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering" } } } @@ -44979,19 +44982,37 @@ }, "responses": { "201": { - "description": "Response", + "description": "Group has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-group" }, "examples": { - "default": { + "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": { @@ -45005,7 +45026,7 @@ "/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}": { "get": { "summary": "Get SCIM provisioning information for an enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nGets information about a SCIM group.", "operationId": "enterprise-admin/get-provisioning-information-for-enterprise-group", "tags": [ "enterprise-admin" @@ -45020,20 +45041,11 @@ }, { "$ref": "#/components/parameters/scim-group-id" - }, - { - "name": "excludedAttributes", - "description": "Attributes to exclude.", - "in": "query", - "required": false, - "schema": { - "type": "string" - } } ], "responses": { "200": { - "description": "Response", + "description": "Success, a group was found", "content": { "application/json": { "schema": { @@ -45046,6 +45058,24 @@ } } } + }, + "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": { @@ -45057,7 +45087,7 @@ }, "put": { "summary": "Set SCIM information for a provisioned enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nReplaces 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.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nReplaces an existing provisioned group’s information.\n\nYou 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": "enterprise-admin/set-information-for-provisioned-enterprise-group", "tags": [ "enterprise-admin" @@ -45079,53 +45109,35 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "displayName": { - "type": "string", - "description": "The name of the SCIM group. This must match the GitHub organization that the group maps to." - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The SCIM user ID for a user." - } - }, - "required": [ - "value" - ] - } - } - }, - "required": [ - "schemas", - "displayName" - ] + "$ref": "#/components/schemas/group" }, "examples": { - "default": { + "group": { + "summary": "Group", "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "displayName": "octo-org", + "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": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc" + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ] } @@ -45136,19 +45148,43 @@ }, "responses": { "200": { - "description": "Response", + "description": "Group was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-group" }, "examples": { - "default": { + "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": { @@ -45160,7 +45196,7 @@ }, "patch": { "summary": "Update an attribute for a SCIM enterprise group", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nAllows 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](https://tools.ietf.org/html/rfc7644#section-3.5.2).", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nUpdate a provisioned group’s individual attributes.\n\nTo 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.\n\nGroup 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": "enterprise-admin/update-attribute-for-enterprise-group", "tags": [ "enterprise-admin" @@ -45182,64 +45218,40 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "Operations": { - "type": "array", - "description": "Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2).", - "minItems": 1, - "items": { - "type": "object", - "properties": { - "op": { - "type": "string", - "enum": [ - "add", - "Add", - "remove", - "Remove", - "replace", - "Replace" - ] - }, - "path": { - "type": "string" - }, - "value": { - "description": "Can be any value - string, number, array or object." - } - }, - "required": [ - "op" - ] - } - } - }, - "required": [ - "schemas", - "Operations" - ] + "$ref": "#/components/schemas/patch-schema" }, "examples": { - "default": { + "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": "remove", + "op": "add", "path": "members", "value": [ { - "value": "aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5" + "value": "879db59-3bdf-4490-ad68-ab880a2694745" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685" } ] } @@ -45252,19 +45264,43 @@ }, "responses": { "200": { - "description": "Response", + "description": "Success, group was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-group" }, "examples": { - "default": { - "$ref": "#/components/examples/scim-enterprise-group-2" + "updateGroup": { + "$ref": "#/components/examples/scim-enterprise-group" + }, + "addMembers": { + "$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": { @@ -45276,7 +45312,7 @@ }, "delete": { "summary": "Delete a SCIM group from an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\n Deletes a SCIM group from an enterprise.", "operationId": "enterprise-admin/delete-scim-group-from-enterprise", "tags": [ "enterprise-admin" @@ -45295,7 +45331,25 @@ ], "responses": { "204": { - "description": "Response" + "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": { @@ -45309,7 +45363,7 @@ "/scim/v2/enterprises/{enterprise}/Users": { "get": { "summary": "List SCIM provisioned identities for an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nRetrieves a paginated list of all provisioned enterprise members, including pending invitations.\n\nWhen 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 Enterprise Server. This can happen in certain cases where an external identity associated with an organization will not match an organization member:\n - 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.\n - 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).\n - 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.\n\nThe 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 Enterprise Server account after completing SSO:\n\n1. The user is granted access by the IdP and is not a member of the GitHub Enterprise Server enterprise.\n\n1. The user attempts to access the GitHub Enterprise Server enterprise and initiates the SAML SSO process, and is not currently signed in to their GitHub Enterprise Server account.\n\n1. 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 Enterprise Server account:\n - If the user signs in, their GitHub Enterprise Server account is linked to this entry.\n - If the user does not sign in (or does not create a new account when prompted), they are not added to the GitHub Enterprise Server enterprise, and the external identity `null` entry remains in place.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nLists provisioned SCIM enterprise members.\n\nWhen 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.\n\nYou can improve query search time by using the `excludedAttributes` query parameter with a value of `groups` to exclude groups from the response.", "operationId": "enterprise-admin/list-provisioned-identities-enterprise", "tags": [ "enterprise-admin" @@ -45320,7 +45374,24 @@ }, "parameters": [ { - "$ref": "#/components/parameters/enterprise" + "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'" + } + } + }, + { + "$ref": "#/components/parameters/excluded-attributes" }, { "$ref": "#/components/parameters/start-index" @@ -45329,22 +45400,16 @@ "$ref": "#/components/parameters/count" }, { - "name": "filter", - "description": "filter results", - "in": "query", - "required": false, - "schema": { - "type": "string" - } + "$ref": "#/components/parameters/enterprise" } ], "responses": { "200": { - "description": "Response", + "description": "Success, either users were found or not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/scim-user-list-enterprise" + "$ref": "#/components/schemas/scim-enterprise-user-list" }, "examples": { "default": { @@ -45353,6 +45418,21 @@ } } } + }, + "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": { @@ -45363,8 +45443,8 @@ } }, "post": { - "summary": "Provision and invite a SCIM enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nProvision enterprise membership for a user, and send organization invitation emails to the email address.\n\nYou 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.", + "summary": "Provision a SCIM enterprise user", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nCreates an external identity for a new SCIM enterprise user.\n\nSCIM 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`.\n\nWhen 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": "enterprise-admin/provision-and-invite-enterprise-user", "tags": [ "enterprise-admin" @@ -45383,106 +45463,14 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "userName": { - "type": "string", - "description": "The username for the user." - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string", - "description": "The first name of the user." - }, - "familyName": { - "type": "string", - "description": "The last name of the user." - } - }, - "required": [ - "givenName", - "familyName" - ] - }, - "emails": { - "type": "array", - "description": "List of user emails.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The email address." - }, - "type": { - "type": "string", - "description": "The type of email address." - }, - "primary": { - "type": "boolean", - "description": "Whether this email address is the primary address." - } - }, - "required": [ - "value", - "type", - "primary" - ] - } - }, - "groups": { - "type": "array", - "description": "List of SCIM group IDs the user is a member of.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } - } - } - }, - "required": [ - "schemas", - "userName", - "name", - "emails" - ] + "$ref": "#/components/schemas/user" }, "examples": { - "default": { - "value": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "userName": "mona.octocat@okta.example.com", - "name": { - "familyName": "Octocat", - "givenName": "Mona" - }, - "emails": [ - { - "value": "mona.octocat@okta.example.com", - "type": "work", - "primary": true - } - ], - "groups": [ - { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" - } - ] - } + "user": { + "$ref": "#/components/examples/in-user" + }, + "enterpriseOwner": { + "$ref": "#/components/examples/in-user-owner" } } } @@ -45490,19 +45478,40 @@ }, "responses": { "201": { - "description": "Response", + "description": "User has been created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-user" }, "examples": { - "default": { + "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": { @@ -45516,7 +45525,7 @@ "/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}": { "get": { "summary": "Get SCIM provisioning information for an enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nGets information about a SCIM user.", "operationId": "enterprise-admin/get-provisioning-information-for-enterprise-user", "tags": [ "enterprise-admin" @@ -45535,7 +45544,7 @@ ], "responses": { "200": { - "description": "Response", + "description": "Success, a user was found", "content": { "application/json": { "schema": { @@ -45548,6 +45557,24 @@ } } } + }, + "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": { @@ -45559,7 +45586,7 @@ }, "put": { "summary": "Set SCIM information for a provisioned enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nReplaces 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-an-enterprise-scim-user) endpoint instead.\n\nYou must at least provide the required values for the user: `userName`, `name`, and `emails`.\n\n**Warning:** Setting `active: false` removes the user from the enterprise, deletes the external identity, and deletes the associated `{scim_user_id}`.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nReplaces an existing provisioned user's information.\n\nYou 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.\n\n**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": "enterprise-admin/set-information-for-provisioned-enterprise-user", "tags": [ "enterprise-admin" @@ -45581,106 +45608,11 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "userName": { - "type": "string", - "description": "The username for the user." - }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string", - "description": "The first name of the user." - }, - "familyName": { - "type": "string", - "description": "The last name of the user." - } - }, - "required": [ - "givenName", - "familyName" - ] - }, - "emails": { - "type": "array", - "description": "List of user emails.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "The email address." - }, - "type": { - "type": "string", - "description": "The type of email address." - }, - "primary": { - "type": "boolean", - "description": "Whether this email address is the primary address." - } - }, - "required": [ - "value", - "type", - "primary" - ] - } - }, - "groups": { - "type": "array", - "description": "List of SCIM group IDs the user is a member of.", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } - } - } - }, - "required": [ - "schemas", - "userName", - "name", - "emails" - ] + "$ref": "#/components/schemas/user" }, "examples": { - "default": { - "value": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], - "userName": "mona.octocat@okta.example.com", - "name": { - "familyName": "Octocat", - "givenName": "Mona" - }, - "emails": [ - { - "value": "mona.octocat@okta.example.com", - "type": "work", - "primary": true - } - ], - "groups": [ - { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" - } - ] - } + "user": { + "$ref": "#/components/examples/in-user" } } } @@ -45688,19 +45620,40 @@ }, "responses": { "200": { - "description": "Response", + "description": "User was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-user" }, "examples": { - "default": { + "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": { @@ -45712,7 +45665,7 @@ }, "patch": { "summary": "Update an attribute for a SCIM enterprise user", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.\n\nAllows 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](https://tools.ietf.org/html/rfc7644#section-3.5.2).\n\n**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.\n\n**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`.\n\n```\n{\n \"Operations\":[{\n \"op\":\"replace\",\n \"value\":{\n \"active\":false\n }\n }]\n}\n```", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nUpdate a provisioned user's individual attributes.\n\nTo 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).\n\n**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.\n\n**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.\n```\n{\n \"Operations\":[{\n \"op\":\"replace\",\n \"value\":{\n \"active\":false\n }\n }]\n}\n```", "operationId": "enterprise-admin/update-attribute-for-enterprise-user", "tags": [ "enterprise-admin" @@ -45734,49 +45687,60 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "schemas": { - "type": "array", - "description": "The SCIM schema URIs.", - "items": { - "type": "string" - } - }, - "Operations": { - "type": "array", - "description": "Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2).", - "items": { - "type": "object" - } - } - }, - "required": [ - "schemas", - "Operations" - ] + "$ref": "#/components/schemas/patch-schema" }, "examples": { - "default": { + "userMultiValuedProperties": { + "summary": "Multi Valued Property", "value": { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { - "op": "add", - "path": "emails", - "value": [ - { - "value": "monalisa@octocat.github.com", - "type": "home" - } - ] + "op": "replace", + "path": "emails[type eq 'work'].value", + "value": "updatedEmail@microsoft.com" }, { "op": "replace", - "path": "name.givenName", - "value": "Monalisa" + "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": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com" + }, + { + "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 } ] } @@ -45787,19 +45751,46 @@ }, "responses": { "200": { - "description": "Response", + "description": "Success, user was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/scim-enterprise-user" }, "examples": { - "default": { - "$ref": "#/components/examples/scim-enterprise-user-2" + "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": { @@ -45811,7 +45802,7 @@ }, "delete": { "summary": "Delete a SCIM user from an enterprise", - "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change.", + "description": "**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.\n\nPermanently suspends a SCIM user from an enterprise, removes all data for the user, obfuscates the login, email, and display name of the user, removes all external-identity SCIM attributes, and deletes the emails, avatar, PATs, SSH keys, OAuth authorizations credentials, GPG keys, and SAML mappings for the user. You will not be able to undo this action.", "operationId": "enterprise-admin/delete-user-from-enterprise", "tags": [ "enterprise-admin" @@ -45830,7 +45821,25 @@ ], "responses": { "204": { - "description": "Response" + "description": "User 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": { @@ -51765,6 +51774,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } @@ -76594,349 +76614,441 @@ "names" ] }, - "scim-group-list-enterprise": { + "group": { "type": "object", + "required": [ + "schemas", + "externalId", + "displayName", + "members" + ], "properties": { "schemas": { "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", "items": { - "type": "string" - } - }, - "totalResults": { - "type": "number" + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ] }, - "itemsPerPage": { - "type": "number" + "externalId": { + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159" }, - "startIndex": { - "type": "number" + "displayName": { + "type": "string", + "description": "A human-readable name for a security group.", + "example": "Engineering" }, - "Resources": { + "members": { "type": "array", + "description": "The group members.", "items": { "type": "object", + "required": [ + "value", + "displayName" + ], "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { + "value": { "type": "string", - "nullable": true + "description": "The local unique identifier for the member", + "example": "23a35c27-23d3-4c03-b4c5-6443c09e7173" }, "displayName": { - "type": "string" - }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" - }, - "display": { - "type": "string" - } - } - } - }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } - } + "type": "string", + "description": "The display name associated with the member", + "example": "Monalisa Octocat" } - }, - "required": [ - "schemas", - "id" - ] + } } } - }, - "required": [ - "schemas", - "totalResults", - "itemsPerPage", - "startIndex", - "Resources" - ] + } }, - "scim-enterprise-group": { + "meta": { "type": "object", + "description": "The metadata associated with the creation/updates to the user.", + "required": [ + "resourceType" + ], "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" + "resourceType": { + "type": "string", + "description": "A type of a resource", + "enum": [ + "User", + "Group" + ], + "example": "User" }, - "externalId": { + "created": { "type": "string", - "nullable": true + "description": "A date and time when the user was created.", + "example": "2022-03-27T19:59:26.000Z" }, - "displayName": { - "type": "string" + "lastModified": { + "type": "string", + "description": "A data and time when the user was last modified.", + "example": "2022-03-27T19:59:26.000Z" }, - "members": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "$ref": { - "type": "string" - }, - "display": { - "type": "string" - } - } - } + "location": { + "type": "string", + "description": "A URL location of an object" + } + } + }, + "scim-enterprise-group": { + "allOf": [ + { + "$ref": "#/components/schemas/group" }, - "meta": { + { "type": "object", + "required": [ + "id", + "meta", + "members" + ], "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the group object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "lastModified": { - "type": "string" + "members": { + "type": "array", + "description": "The security group members.", + "example": [ + { + "value": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" + }, + { + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" + } + ] }, - "location": { - "type": "string" + "meta": { + "$ref": "#/components/schemas/meta" } } } - }, - "required": [ - "schemas", - "id" ] }, - "scim-user-list-enterprise": { + "scim-enterprise-group-list": { "type": "object", + "required": [ + "schemas", + "totalResults", + "Resources", + "startIndex", + "itemsPerPage" + ], "properties": { "schemas": { "type": "array", + "description": "The URIs that are used to indicate the namespaces of the list SCIM schemas.", "items": { - "type": "string" - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] + }, + "example": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] }, "totalResults": { - "type": "number" + "type": "integer", + "description": "Number of results found", + "example": 1 }, - "itemsPerPage": { - "type": "number" + "Resources": { + "type": "array", + "description": "Information about each provisioned group.", + "items": { + "$ref": "#/components/schemas/scim-enterprise-group" + } }, "startIndex": { - "type": "number" + "type": "integer", + "description": "A starting index for the returned page", + "example": 1 }, - "Resources": { + "itemsPerPage": { + "type": "integer", + "description": "Number of objects per page", + "example": 20 + } + } + }, + "patch-schema": { + "type": "object", + "required": [ + "Operations", + "schemas" + ], + "properties": { + "Operations": { "type": "array", + "description": "patch operations list", "items": { "type": "object", + "required": [ + "op" + ], "properties": { - "schemas": { - "type": "array", - "items": { - "type": "string" - } - }, - "id": { - "type": "string" - }, - "externalId": { - "type": "string" + "op": { + "type": "string", + "enum": [ + "add", + "replace", + "remove" + ] }, - "userName": { + "path": { "type": "string" }, - "name": { - "type": "object", - "properties": { - "givenName": { - "type": "string" - }, - "familyName": { - "type": "string" - } - } - }, - "emails": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "primary": { - "type": "boolean" - }, - "type": { - "type": "string" - } - } - } - }, - "groups": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } - } - }, - "active": { - "type": "boolean" - }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } - } + "value": { + "type": "string", + "description": "Corresponding 'value' of that field specified by 'path'" } - }, - "required": [ - "schemas", - "id" + } + } + }, + "schemas": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } } - }, + } + }, + "user-name": { + "type": "object", "required": [ - "schemas", - "totalResults", - "itemsPerPage", - "startIndex", - "Resources" - ] + "familyName", + "givenName" + ], + "properties": { + "formatted": { + "type": "string", + "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", + "example": "Ms. Mona Lisa Octocat" + }, + "familyName": { + "type": "string", + "description": "The family name of the user.", + "example": "Octocat" + }, + "givenName": { + "type": "string", + "description": "The given name of the user.", + "example": "Mona" + }, + "middleName": { + "type": "string", + "description": "The middle name(s) of the user.", + "example": "Lisa" + } + } }, - "scim-enterprise-user": { + "user-emails": { + "type": "array", + "description": "The emails for the user.", + "items": { + "type": "object", + "required": [ + "value", + "type", + "primary" + ], + "properties": { + "value": { + "type": "string", + "description": "The email address.", + "example": "mlisa@example.com" + }, + "type": { + "type": "string", + "description": "The type of email address.", + "example": "work" + }, + "primary": { + "type": "boolean", + "description": "Whether this email address is the primary address.", + "example": true + } + } + } + }, + "user-role": { + "type": "array", + "description": "The roles assigned to the user.", + "items": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "type": "string", + "description": "The role value representing a user role in GitHub.", + "enum": [ + "User", + "Enterprise Owner" + ], + "example": "User" + }, + "primary": { + "type": "boolean", + "description": "Is the role a primary role for the user.", + "example": false + } + } + } + }, + "user": { "type": "object", + "required": [ + "schemas", + "externalId", + "userName", + "active", + "displayName", + "emails" + ], "properties": { "schemas": { "type": "array", + "description": "The URIs that are used to indicate the namespaces of the SCIM schemas.", "items": { - "type": "string" - } - }, - "id": { - "type": "string" + "type": "string", + "enum": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] + }, + "example": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ] }, "externalId": { - "type": "string" + "type": "string", + "description": "A unique identifier for the resource as defined by the provisioning client.", + "example": "E012345" + }, + "active": { + "type": "boolean", + "description": "Whether the user active in the IdP.", + "example": true }, "userName": { - "type": "string" + "type": "string", + "description": "The username for the user.", + "example": "E012345" }, "name": { + "$ref": "#/components/schemas/user-name" + }, + "displayName": { + "type": "string", + "description": "A human-readable name for the user.", + "example": "Mona Lisa" + }, + "emails": { + "$ref": "#/components/schemas/user-emails" + }, + "roles": { + "$ref": "#/components/schemas/user-role" + } + } + }, + "scim-enterprise-user": { + "allOf": [ + { + "$ref": "#/components/schemas/user" + }, + { "type": "object", + "required": [ + "id", + "meta" + ], "properties": { - "givenName": { - "type": "string" + "id": { + "type": "string", + "description": "The internally generated id for the user object.", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" }, - "familyName": { - "type": "string" + "groups": { + "type": "array", + "description": "Provisioned SCIM groups that the user is a member of." + }, + "meta": { + "$ref": "#/components/schemas/meta" } } - }, - "emails": { + } + ] + }, + "scim-enterprise-user-list": { + "type": "object", + "required": [ + "schemas", + "totalResults", + "Resources", + "startIndex", + "itemsPerPage" + ], + "properties": { + "schemas": { "type": "array", + "description": "The URIs that are used to indicate the namespaces of the list SCIM schemas.", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "type": { - "type": "string" - }, - "primary": { - "type": "boolean" - } - } - } + "type": "string", + "enum": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] + }, + "example": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ] }, - "groups": { + "totalResults": { + "type": "integer", + "description": "Number of results found", + "example": 1 + }, + "Resources": { "type": "array", + "description": "Information about each provisioned account.", "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - } + "$ref": "#/components/schemas/scim-enterprise-user" } }, - "active": { - "type": "boolean" + "startIndex": { + "type": "integer", + "description": "A starting index for the returned page", + "example": 1 }, - "meta": { - "type": "object", - "properties": { - "resourceType": { - "type": "string" - }, - "created": { - "type": "string" - }, - "lastModified": { - "type": "string" - }, - "location": { - "type": "string" - } - } + "itemsPerPage": { + "type": "integer", + "description": "Number of objects per page", + "example": 20 } - }, - "required": [ - "schemas", - "id" - ] + } }, "search-result-text-matches": { "title": "Search Result Text Matches", @@ -99450,58 +99562,37 @@ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], - "totalResults": 2, - "itemsPerPage": 2, - "startIndex": 1, + "totalResults": 1, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], - "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "id": "927fa2c08dcb4a7fae9e", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "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" + "value": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" } } - ] + ], + "startIndex": 1, + "itemsPerPage": 20 } }, "scim-enterprise-group": { @@ -99510,48 +99601,25 @@ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "abcd27f8-a9aa-11ea-8221-f59b2be9cccc", - "externalId": null, - "displayName": "octo-org", + "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159", + "displayName": "Engineering", "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": "879db59-3bdf-4490-ad68-ab880a2694745", + "$+ref": "https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745", + "displayName": "User 1" }, { - "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" - } - } - }, - "scim-enterprise-group-2": { - "value": { - "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": "0db508eb-91e2-46e4-809c-30dcbda0c685", + "$+ref": "https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685", + "displayName": "User 2" } ], "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e" } } }, @@ -99560,140 +99628,138 @@ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], - "totalResults": 2, - "itemsPerPage": 2, - "startIndex": 1, + "totalResults": 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" - } - ], + "externalId": "E012345", + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", "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", + "userName": "E012345", "name": { - "givenName": "hu", - "familyName": "bot" + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" }, + "displayName": "Mona Lisa", "emails": [ { - "value": "hubot@example.com", + "value": "mlisa@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" - } + "roles": [ + { + "value": "User", + "primary": false + } + ] } - ] + ], + "startIndex": 1, + "itemsPerPage": 20 } }, - "scim-enterprise-user": { + "in-user": { + "summary": "User", "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], - "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc", - "externalId": "00dowz5dr9oSfDFRA0h7", - "userName": "mona.octocat@okta.example.com", + "externalId": "E012345", + "active": true, + "userName": "E012345", "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", "givenName": "Mona", - "familyName": "Octocat" + "middleName": "Lisa" }, + "displayName": "Mona Lisa", "emails": [ { - "value": "mona.octocat@okta.example.com", + "value": "mlisa@example.com", "type": "work", "primary": true } ], - "groups": [ + "roles": [ { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "value": "User", + "primary": false } + ] + } + }, + "in-user-owner": { + "summary": "Enterprise Owner", + "value": { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" ], + "externalId": "E012345", "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" - } + "userName": "E012345", + "name": { + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" + }, + "displayName": "Mona Lisa", + "emails": [ + { + "value": "mlisa@example.com", + "type": "work", + "primary": true + } + ], + "roles": [ + { + "value": "Enterprise Owner", + "primary": false + } + ] } }, - "scim-enterprise-user-2": { + "scim-enterprise-user": { "value": { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], - "id": "92b58aaa-a1d6-11ea-8227-b9ce9e023ccc", - "externalId": "00dowz5dr9oSfDFRA0h7", - "userName": "mona.octocat@okta.example.com", + "id": "7fce0092-d52e-4f76-b727-3955bd72c939", + "externalId": "E012345", + "active": true, + "userName": "E012345", "name": { - "givenName": "Monalisa", - "familyName": "Octocat" + "formatted": "Ms. Mona Lisa Octocat", + "familyName": "Octocat", + "givenName": "Mona", + "middleName": "Lisa" }, + "displayName": "Mona Lisa", "emails": [ { - "value": "mona.octocat@okta.example.com", + "value": "mlisa@example.com", "type": "work", "primary": true - }, - { - "value": "monalisa@octocat.github.com", - "type": "home" } ], - "groups": [ + "roles": [ { - "value": "468dd3fa-a1d6-11ea-9031-15a1f0d7811d" + "value": "User", + "primary": false } ], - "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" + "created": "2012-03-27T19:59:26.000Z", + "lastModified": "2018-03-27T19:59:26.000Z", + "location": "https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939" } } }, @@ -103407,31 +103473,48 @@ "type": "integer" } }, + "excluded-attributes": { + "name": "excludedAttributes", + "description": "Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "example": "members" + } + }, "start-index": { "name": "startIndex", - "description": "Used for pagination: the index of the first result to return.", + "description": "Used for pagination: the starting index of the first result to return when paginating through values.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "integer", + "default": 1, + "format": "int32", + "example": 1 } }, "count": { "name": "count", - "description": "Used for pagination: the number of results to return.", + "description": "Used for pagination: the number of results to return per page.", "in": "query", "required": false, "schema": { - "type": "integer" + "type": "integer", + "default": 30, + "format": "int32", + "example": 1 } }, "scim-group-id": { "name": "scim_group_id", - "description": "Identifier generated by the GitHub SCIM endpoint.", + "description": "A unique identifier of the SCIM group.", "in": "path", "required": true, "schema": { - "type": "string" + "type": "string", + "example": "7fce0092-d52e-4f76-b727-3955bd72c939" } }, "scim-user-id": { @@ -103789,6 +103872,60 @@ }, "no_content": { "description": "A header with no content is returned." + }, + "scim_bad_request": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + }, + "application/scim+json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + } + } + }, + "authorization_failure": { + "description": "Authorization failure" + }, + "permission_denied": { + "description": "Permission denied" + }, + "scim_too_many_requests": { + "description": "Too many requests", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + }, + "application/scim+json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + } + } + }, + "scim_internal_error": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + }, + "application/scim+json": { + "schema": { + "$ref": "#/components/schemas/scim-error" + } + } + } + }, + "duplicate_record_detected": { + "description": "Duplicate record detected" } } } diff --git a/descriptions/ghes-3.6/ghes-3.6.yaml b/descriptions/ghes-3.6/ghes-3.6.yaml index 929fa20839..e52b592f79 100644 --- a/descriptions/ghes-3.6/ghes-3.6.yaml +++ b/descriptions/ghes-3.6/ghes-3.6.yaml @@ -23104,6 +23104,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -28891,12 +28897,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -31125,6 +31135,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -31982,8 +31997,12 @@ paths: "/scim/v2/enterprises/{enterprise}/Groups": get: summary: List provisioned SCIM groups for an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/list-provisioned-groups-enterprise tags: - enterprise-admin @@ -31991,42 +32010,56 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#list-provisioned-scim-groups-for-an-enterprise parameters: - - "$ref": "#/components/parameters/enterprise" - - "$ref": "#/components/parameters/start-index" - - "$ref": "#/components/parameters/count" - name: filter - description: filter results - in: query - required: false - schema: - type: string - - name: excludedAttributes - description: attributes to exclude + 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 + - "$ref": "#/components/parameters/excluded-attributes" + - "$ref": "#/components/parameters/start-index" + - "$ref": "#/components/parameters/count" + - "$ref": "#/components/parameters/enterprise" responses: '200': - description: Response + description: Success, either groups were found or not found content: application/json: schema: - "$ref": "#/components/schemas/scim-group-list-enterprise" + "$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: false category: enterprise-admin subcategory: scim post: - summary: Provision a SCIM enterprise group and invite users + summary: Provision a SCIM enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* 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. + 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: enterprise-admin/provision-and-invite-enterprise-group tags: - enterprise-admin @@ -32040,49 +32073,36 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - displayName: - type: string - description: The name of the SCIM group. This must match the GitHub - organization that the group maps to. - members: - type: array - items: - type: object - properties: - value: - type: string - description: The SCIM user ID for a user. - required: - - value - required: - - schemas - - displayName + "$ref": "#/components/schemas/group" examples: - default: + group: value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - displayName: octo-org - members: - - value: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - - value: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + displayName: Engineering responses: '201': - description: Response + description: Group has been created content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-group" examples: - default: + 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: false @@ -32091,8 +32111,10 @@ paths: "/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}": get: summary: Get SCIM provisioning information for an enterprise group - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/get-provisioning-information-for-enterprise-group tags: - enterprise-admin @@ -32102,15 +32124,9 @@ paths: parameters: - "$ref": "#/components/parameters/enterprise" - "$ref": "#/components/parameters/scim-group-id" - - name: excludedAttributes - description: Attributes to exclude. - in: query - required: false - schema: - type: string responses: '200': - description: Response + description: Success, a group was found content: application/json: schema: @@ -32118,6 +32134,18 @@ paths: 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: false @@ -32126,9 +32154,11 @@ paths: put: summary: Set SCIM information for a provisioned enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - 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. + 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: enterprise-admin/set-information-for-provisioned-enterprise-group tags: - enterprise-admin @@ -32143,49 +32173,53 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - displayName: - type: string - description: The name of the SCIM group. This must match the GitHub - organization that the group maps to. - members: - type: array - items: - type: object - properties: - value: - type: string - description: The SCIM user ID for a user. - required: - - value - required: - - schemas - - displayName + "$ref": "#/components/schemas/group" examples: - default: + group: + summary: Group value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - displayName: octo-org + 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: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - - value: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 responses: '200': - description: Response + description: Group was updated content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-group" examples: - default: + 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: false @@ -32194,9 +32228,13 @@ paths: patch: summary: Update an attribute for a SCIM enterprise group description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - 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](https://tools.ietf.org/html/rfc7644#section-3.5.2). + 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: enterprise-admin/update-attribute-for-enterprise-group tags: - enterprise-admin @@ -32211,58 +32249,54 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - Operations: - type: array - description: Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2). - minItems: 1 - items: - type: object - properties: - op: - type: string - enum: - - add - - Add - - remove - - Remove - - replace - - Replace - path: - type: string - value: - description: Can be any value - string, number, array or object. - required: - - op - required: - - schemas - - Operations + "$ref": "#/components/schemas/patch-schema" examples: - default: + updateGroup: + summary: Update Group value: schemas: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: - - op: remove + - 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: aaaa8c34-a6b2-11ea-9d70-bbbbbd1c8fd5 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 responses: '200': - description: Response + description: Success, group was updated content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-group" examples: - default: - "$ref": "#/components/examples/scim-enterprise-group-2" + updateGroup: + "$ref": "#/components/examples/scim-enterprise-group" + addMembers: + "$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: false @@ -32270,8 +32304,10 @@ paths: subcategory: scim delete: summary: Delete a SCIM group from an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/delete-scim-group-from-enterprise tags: - enterprise-admin @@ -32283,7 +32319,19 @@ paths: - "$ref": "#/components/parameters/scim-group-id" responses: '204': - description: Response + 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: false @@ -32293,24 +32341,13 @@ paths: get: summary: List SCIM provisioned identities for an enterprise description: |- - **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. + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change. - 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 Enterprise Server. 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. + Lists provisioned SCIM enterprise members. - 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 Enterprise Server account after completing SSO: + 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. - 1. The user is granted access by the IdP and is not a member of the GitHub Enterprise Server enterprise. - - 1. The user attempts to access the GitHub Enterprise Server enterprise and initiates the SAML SSO process, and is not currently signed in to their GitHub Enterprise Server account. - - 1. 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 Enterprise Server account: - - If the user signs in, their GitHub Enterprise Server 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 Server enterprise, and the external identity `null` entry remains in place. + You can improve query search time by using the `excludedAttributes` query parameter with a value of `groups` to exclude groups from the response. operationId: enterprise-admin/list-provisioned-identities-enterprise tags: - enterprise-admin @@ -32318,38 +32355,59 @@ paths: description: API method documentation url: https://docs.github.com/enterprise-server@3.6/rest/reference/enterprise-admin#list-scim-provisioned-identities-for-an-enterprise parameters: - - "$ref": "#/components/parameters/enterprise" - - "$ref": "#/components/parameters/start-index" - - "$ref": "#/components/parameters/count" - name: filter - description: filter results + 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' + - "$ref": "#/components/parameters/excluded-attributes" + - "$ref": "#/components/parameters/start-index" + - "$ref": "#/components/parameters/count" + - "$ref": "#/components/parameters/enterprise" responses: '200': - description: Response + description: Success, either users were found or not found content: application/json: schema: - "$ref": "#/components/schemas/scim-user-list-enterprise" + "$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: false category: enterprise-admin subcategory: scim post: - summary: Provision and invite a SCIM enterprise user + summary: Provision a SCIM enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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. - Provision enterprise membership for a user, and send organization invitation emails to the email address. + 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`. - 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. + 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: enterprise-admin/provision-and-invite-enterprise-user tags: - enterprise-admin @@ -32363,85 +32421,36 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - userName: - type: string - description: The username for the user. - name: - type: object - properties: - givenName: - type: string - description: The first name of the user. - familyName: - type: string - description: The last name of the user. - required: - - givenName - - familyName - emails: - type: array - description: List of user emails. - items: - type: object - properties: - value: - type: string - description: The email address. - type: - type: string - description: The type of email address. - primary: - type: boolean - description: Whether this email address is the primary address. - required: - - value - - type - - primary - groups: - type: array - description: List of SCIM group IDs the user is a member of. - items: - type: object - properties: - value: - type: string - required: - - schemas - - userName - - name - - emails + "$ref": "#/components/schemas/user" examples: - default: - value: - schemas: - - urn:ietf:params:scim:schemas:core:2.0:User - userName: mona.octocat@okta.example.com - name: - familyName: Octocat - givenName: Mona - emails: - - value: mona.octocat@okta.example.com - type: work - primary: true - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d + user: + "$ref": "#/components/examples/in-user" + enterpriseOwner: + "$ref": "#/components/examples/in-user-owner" responses: '201': - description: Response + description: User has been created content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-user" examples: - default: + 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: false @@ -32450,8 +32459,10 @@ paths: "/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}": get: summary: Get SCIM provisioning information for an enterprise user - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + 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: enterprise-admin/get-provisioning-information-for-enterprise-user tags: - enterprise-admin @@ -32463,7 +32474,7 @@ paths: - "$ref": "#/components/parameters/scim-user-id" responses: '200': - description: Response + description: Success, a user was found content: application/json: schema: @@ -32471,6 +32482,18 @@ paths: 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: false @@ -32479,13 +32502,13 @@ paths: put: summary: Set SCIM information for a provisioned enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **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-an-enterprise-scim-user) endpoint instead. + Replaces an existing provisioned user's information. - You must at least provide the required values for the user: `userName`, `name`, and `emails`. + 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` removes the user from the enterprise, deletes the external identity, and deletes the associated `{scim_user_id}`. + **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: enterprise-admin/set-information-for-provisioned-enterprise-user tags: - enterprise-admin @@ -32500,85 +32523,34 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - userName: - type: string - description: The username for the user. - name: - type: object - properties: - givenName: - type: string - description: The first name of the user. - familyName: - type: string - description: The last name of the user. - required: - - givenName - - familyName - emails: - type: array - description: List of user emails. - items: - type: object - properties: - value: - type: string - description: The email address. - type: - type: string - description: The type of email address. - primary: - type: boolean - description: Whether this email address is the primary address. - required: - - value - - type - - primary - groups: - type: array - description: List of SCIM group IDs the user is a member of. - items: - type: object - properties: - value: - type: string - required: - - schemas - - userName - - name - - emails + "$ref": "#/components/schemas/user" examples: - default: - value: - schemas: - - urn:ietf:params:scim:schemas:core:2.0:User - userName: mona.octocat@okta.example.com - name: - familyName: Octocat - givenName: Mona - emails: - - value: mona.octocat@okta.example.com - type: work - primary: true - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d + user: + "$ref": "#/components/examples/in-user" responses: '200': - description: Response + description: User was updated content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-user" examples: - default: + 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: false @@ -32587,14 +32559,15 @@ paths: patch: summary: Update an attribute for a SCIM enterprise user description: |- - **Note:** The SCIM API endpoints for enterprise accounts are currently in beta and are subject to change. + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* 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](https://tools.ietf.org/html/rfc7644#section-3.5.2). + Update a provisioned user's individual attributes. - **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. + 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). - **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`. + **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":[{ @@ -32619,45 +32592,69 @@ paths: content: application/json: schema: - type: object - properties: - schemas: - type: array - description: The SCIM schema URIs. - items: - type: string - Operations: - type: array - description: Array of [SCIM operations](https://tools.ietf.org/html/rfc7644#section-3.5.2). - items: - type: object - required: - - schemas - - Operations + "$ref": "#/components/schemas/patch-schema" examples: - default: + 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: updatedEmail@microsoft.com + - 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: add - path: emails - value: - - value: monalisa@octocat.github.com - type: home - op: replace - path: name.givenName - value: Monalisa + path: userName + value: 5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com + - 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: Response + description: Success, user was updated content: application/json: schema: "$ref": "#/components/schemas/scim-enterprise-user" examples: - default: - "$ref": "#/components/examples/scim-enterprise-user-2" + 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: false @@ -32665,8 +32662,10 @@ paths: subcategory: scim delete: summary: Delete a SCIM user from an enterprise - description: "**Note:** The SCIM API endpoints for enterprise accounts are currently - in beta and are subject to change." + description: |- + **Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change. + + Permanently suspends a SCIM user from an enterprise, removes all data for the user, obfuscates the login, email, and display name of the user, removes all external-identity SCIM attributes, and deletes the emails, avatar, PATs, SSH keys, OAuth authorizations credentials, GPG keys, and SAML mappings for the user. You will not be able to undo this action. operationId: enterprise-admin/delete-user-from-enterprise tags: - enterprise-admin @@ -32678,7 +32677,19 @@ paths: - "$ref": "#/components/parameters/scim-user-id" responses: '204': - description: Response + description: User 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: false @@ -37062,6 +37073,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response @@ -56002,234 +56021,326 @@ components: type: string required: - names - scim-group-list-enterprise: + group: type: object - properties: - schemas: - type: array - items: - type: string - totalResults: - type: number - itemsPerPage: - type: number - startIndex: - type: number - Resources: - type: array - items: - type: object - properties: - schemas: - type: array - items: - type: string - id: - type: string - externalId: - type: string - nullable: true - displayName: - type: string - members: - type: array - items: - type: object - properties: - value: - type: string - "$ref": - type: string - display: - type: string - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id required: - schemas - - totalResults - - itemsPerPage - - startIndex - - Resources - scim-enterprise-group: - type: object + - externalId + - displayName + - members properties: schemas: type: array + description: The URIs that are used to indicate the namespaces of the SCIM + schemas. items: type: string - id: - type: string + enum: + - urn:ietf:params:scim:schemas:core:2.0:Group + example: + - urn:ietf:params:scim:schemas:core:2.0:Group externalId: type: string - nullable: true + description: A unique identifier for the resource as defined by the provisioning + client. + example: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 displayName: type: string + description: A human-readable name for a security group. + example: Engineering members: type: array + description: The group members. items: type: object + required: + - value + - displayName properties: value: type: string - "$ref": - type: string - display: + description: The local unique identifier for the member + example: 23a35c27-23d3-4c03-b4c5-6443c09e7173 + displayName: type: string - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string + description: The display name associated with the member + example: Monalisa Octocat + meta: + type: object + description: The metadata associated with the creation/updates to the user. required: - - schemas - - id - scim-user-list-enterprise: + - resourceType + properties: + resourceType: + type: string + description: A type of a resource + enum: + - User + - Group + example: User + created: + type: string + description: A date and time when the user was created. + example: '2022-03-27T19:59:26.000Z' + lastModified: + type: string + description: A data and time when the user was last modified. + example: '2022-03-27T19:59:26.000Z' + location: + type: string + description: A URL location of an object + scim-enterprise-group: + allOf: + - "$ref": "#/components/schemas/group" + - type: object + required: + - id + - meta + - members + properties: + id: + type: string + description: The internally generated id for the group object. + example: 7fce0092-d52e-4f76-b727-3955bd72c939 + members: + type: array + description: The security group members. + example: + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 + meta: + "$ref": "#/components/schemas/meta" + scim-enterprise-group-list: type: object + required: + - schemas + - totalResults + - Resources + - startIndex + - itemsPerPage properties: schemas: type: array + description: The URIs that are used to indicate the namespaces of the list + SCIM schemas. items: type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: - type: number - itemsPerPage: - type: number - startIndex: - type: number + type: integer + description: Number of results found + example: 1 Resources: type: array + description: Information about each provisioned group. + items: + "$ref": "#/components/schemas/scim-enterprise-group" + startIndex: + type: integer + description: A starting index for the returned page + example: 1 + itemsPerPage: + type: integer + description: Number of objects per page + example: 20 + patch-schema: + type: object + required: + - Operations + - schemas + properties: + Operations: + type: array + description: patch operations list items: type: object + required: + - op properties: - schemas: - type: array - items: - type: string - id: + op: type: string - externalId: + enum: + - add + - replace + - remove + path: type: string - userName: + value: type: string - name: - type: object - properties: - givenName: - type: string - familyName: - type: string - emails: - type: array - items: - type: object - properties: - value: - type: string - primary: - type: boolean - type: - type: string - groups: - type: array - items: - type: object - properties: - value: - type: string - active: - type: boolean - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id + description: Corresponding 'value' of that field specified by 'path' + schemas: + type: array + items: + type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:PatchOp + user-name: + type: object required: - - schemas - - totalResults - - itemsPerPage - - startIndex - - Resources - scim-enterprise-user: + - familyName + - givenName + properties: + formatted: + type: string + description: The full name, including all middle names, titles, and suffixes + as appropriate, formatted for display. + example: Ms. Mona Lisa Octocat + familyName: + type: string + description: The family name of the user. + example: Octocat + givenName: + type: string + description: The given name of the user. + example: Mona + middleName: + type: string + description: The middle name(s) of the user. + example: Lisa + user-emails: + type: array + description: The emails for the user. + items: + type: object + required: + - value + - type + - primary + properties: + value: + type: string + description: The email address. + example: mlisa@example.com + type: + type: string + description: The type of email address. + example: work + primary: + type: boolean + description: Whether this email address is the primary address. + example: true + user-role: + type: array + description: The roles assigned to the user. + items: + type: object + required: + - value + properties: + value: + type: string + description: The role value representing a user role in GitHub. + enum: + - User + - Enterprise Owner + example: User + primary: + type: boolean + description: Is the role a primary role for the user. + example: false + user: type: object + required: + - schemas + - externalId + - userName + - active + - displayName + - emails properties: schemas: type: array + description: The URIs that are used to indicate the namespaces of the SCIM + schemas. items: type: string - id: - type: string + enum: + - urn:ietf:params:scim:schemas:core:2.0:User + example: + - urn:ietf:params:scim:schemas:core:2.0:User externalId: type: string + description: A unique identifier for the resource as defined by the provisioning + client. + example: E012345 + active: + type: boolean + description: Whether the user active in the IdP. + example: true userName: type: string + description: The username for the user. + example: E012345 name: - type: object - properties: - givenName: - type: string - familyName: - type: string + "$ref": "#/components/schemas/user-name" + displayName: + type: string + description: A human-readable name for the user. + example: Mona Lisa emails: + "$ref": "#/components/schemas/user-emails" + roles: + "$ref": "#/components/schemas/user-role" + scim-enterprise-user: + allOf: + - "$ref": "#/components/schemas/user" + - type: object + required: + - id + - meta + properties: + id: + type: string + description: The internally generated id for the user object. + example: 7fce0092-d52e-4f76-b727-3955bd72c939 + groups: + type: array + description: Provisioned SCIM groups that the user is a member of. + meta: + "$ref": "#/components/schemas/meta" + scim-enterprise-user-list: + type: object + required: + - schemas + - totalResults + - Resources + - startIndex + - itemsPerPage + properties: + schemas: type: array + description: The URIs that are used to indicate the namespaces of the list + SCIM schemas. items: - type: object - properties: - value: - type: string - type: - type: string - primary: - type: boolean - groups: + type: string + enum: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + example: + - urn:ietf:params:scim:api:messages:2.0:ListResponse + totalResults: + type: integer + description: Number of results found + example: 1 + Resources: type: array + description: Information about each provisioned account. items: - type: object - properties: - value: - type: string - active: - type: boolean - meta: - type: object - properties: - resourceType: - type: string - created: - type: string - lastModified: - type: string - location: - type: string - required: - - schemas - - id + "$ref": "#/components/schemas/scim-enterprise-user" + startIndex: + type: integer + description: A starting index for the returned page + example: 1 + itemsPerPage: + type: integer + description: Number of objects per page + example: 20 search-result-text-matches: title: Search Result Text Matches type: array @@ -75941,169 +76052,141 @@ components: value: schemas: - urn:ietf:params:scim:api:messages:2.0:ListResponse - totalResults: 2 - itemsPerPage: 2 - startIndex: 1 + totalResults: 1 Resources: - schemas: - urn:ietf:params:scim:schemas:core:2.0:Group - id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - displayName: octo-org + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + id: 927fa2c08dcb4a7fae9e + displayName: Engineering 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 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 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: - 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e + startIndex: 1 + itemsPerPage: 20 scim-enterprise-group: value: schemas: - urn:ietf:params:scim:schemas:core:2.0:Group id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - displayName: octo-org + externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159 + displayName: Engineering 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 + - value: 879db59-3bdf-4490-ad68-ab880a2694745 + "$+ref": https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745 + displayName: User 1 + - value: 0db508eb-91e2-46e4-809c-30dcbda0c685 + "$+ref": https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685 + displayName: User 2 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 - scim-enterprise-group-2: - value: - schemas: - - urn:ietf:params:scim:schemas:core:2.0:Group - id: abcd27f8-a9aa-11ea-8221-f59b2be9cccc - externalId: - 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e scim-enterprise-user-list: value: schemas: - urn:ietf:params:scim:api:messages:2.0:ListResponse - totalResults: 2 - itemsPerPage: 2 - startIndex: 1 + totalResults: 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 + externalId: E012345 + id: 7fce0092-d52e-4f76-b727-3955bd72c939 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 + userName: E012345 name: - givenName: hu - familyName: bot + formatted: Ms. Mona Lisa Octocat + familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: hubot@example.com + - value: mlisa@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 - scim-enterprise-user: + roles: + - value: User + primary: false + startIndex: 1 + itemsPerPage: 20 + in-user: + summary: User value: schemas: - urn:ietf:params:scim:schemas:core:2.0:User - id: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - externalId: 00dowz5dr9oSfDFRA0h7 - userName: mona.octocat@okta.example.com + externalId: E012345 + active: true + userName: E012345 name: - givenName: Mona + formatted: Ms. Mona Lisa Octocat familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: mona.octocat@okta.example.com + - value: mlisa@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 - scim-enterprise-user-2: + roles: + - value: User + primary: false + in-user-owner: + summary: Enterprise Owner value: schemas: - urn:ietf:params:scim:schemas:core:2.0:User - id: 92b58aaa-a1d6-11ea-8227-b9ce9e023ccc - externalId: 00dowz5dr9oSfDFRA0h7 - userName: mona.octocat@okta.example.com + externalId: E012345 + active: true + userName: E012345 name: - givenName: Monalisa + formatted: Ms. Mona Lisa Octocat familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa emails: - - value: mona.octocat@okta.example.com + - value: mlisa@example.com type: work primary: true - - value: monalisa@octocat.github.com - type: home - groups: - - value: 468dd3fa-a1d6-11ea-9031-15a1f0d7811d + roles: + - value: Enterprise Owner + primary: false + scim-enterprise-user: + value: + schemas: + - urn:ietf:params:scim:schemas:core:2.0:User + id: 7fce0092-d52e-4f76-b727-3955bd72c939 + externalId: E012345 active: true + userName: E012345 + name: + formatted: Ms. Mona Lisa Octocat + familyName: Octocat + givenName: Mona + middleName: Lisa + displayName: Mona Lisa + emails: + - value: mlisa@example.com + type: work + primary: true + roles: + - value: User + primary: false 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 + created: '2012-03-27T19:59:26.000Z' + lastModified: '2018-03-27T19:59:26.000Z' + location: https://api.github.localhost/scim/v2/Users/7fce0092-d52e-4f76-b727-3955bd72c939 code-search-result-item-paginated: value: total_count: 7 @@ -79309,27 +79392,44 @@ components: required: false schema: type: integer + excluded-attributes: + name: excludedAttributes + description: Excludes the specified attribute from being returned in the results. + Using this parameter can speed up response time. + in: query + required: false + schema: + type: string + example: members start-index: name: startIndex - description: 'Used for pagination: the index of the first result to return.' + description: 'Used for pagination: the starting index of the first result to + return when paginating through values.' in: query required: false schema: type: integer + default: 1 + format: int32 + example: 1 count: name: count - description: 'Used for pagination: the number of results to return.' + description: 'Used for pagination: the number of results to return per page.' in: query required: false schema: type: integer + default: 30 + format: int32 + example: 1 scim-group-id: name: scim_group_id - description: Identifier generated by the GitHub SCIM endpoint. + description: A unique identifier of the SCIM group. in: path required: true schema: type: string + example: 7fce0092-d52e-4f76-b727-3955bd72c939 scim-user-id: name: scim_user_id description: The unique identifier of the SCIM user. @@ -79562,3 +79662,36 @@ components: description: Found no_content: description: A header with no content is returned. + scim_bad_request: + description: Bad request + content: + application/json: + schema: + "$ref": "#/components/schemas/scim-error" + application/scim+json: + schema: + "$ref": "#/components/schemas/scim-error" + authorization_failure: + description: Authorization failure + permission_denied: + description: Permission denied + scim_too_many_requests: + description: Too many requests + content: + application/json: + schema: + "$ref": "#/components/schemas/scim-error" + application/scim+json: + schema: + "$ref": "#/components/schemas/scim-error" + scim_internal_error: + description: Internal server error + content: + application/json: + schema: + "$ref": "#/components/schemas/scim-error" + application/scim+json: + schema: + "$ref": "#/components/schemas/scim-error" + duplicate_record_detected: + description: Duplicate record detected diff --git a/descriptions/github.ae/dereferenced/github.ae.deref.json b/descriptions/github.ae/dereferenced/github.ae.deref.json index 460d9f076e..334233ab44 100644 --- a/descriptions/github.ae/dereferenced/github.ae.deref.json +++ b/descriptions/github.ae/dereferenced/github.ae.deref.json @@ -170640,6 +170640,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -264589,7 +264598,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -264597,6 +264606,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -287777,6 +287794,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -325207,6 +325232,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/github.ae/dereferenced/github.ae.deref.yaml b/descriptions/github.ae/dereferenced/github.ae.deref.yaml index 4789438a1b..9982cf7dad 100644 --- a/descriptions/github.ae/dereferenced/github.ae.deref.yaml +++ b/descriptions/github.ae/dereferenced/github.ae.deref.yaml @@ -40967,6 +40967,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -52132,12 +52138,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -56467,6 +56477,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -63317,6 +63332,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response diff --git a/descriptions/github.ae/github.ae.json b/descriptions/github.ae/github.ae.json index 3c7b51bc2f..0f3795d83e 100644 --- a/descriptions/github.ae/github.ae.json +++ b/descriptions/github.ae/github.ae.json @@ -26079,6 +26079,15 @@ "description": "Optional parameter to specify the organization name if forking into an organization." } } + }, + "examples": { + "default": { + "value": { + "organization": "octocat", + "name": "Hello-World", + "default_branch_only": true + } + } } } } @@ -34289,7 +34298,7 @@ }, "merge_method": { "type": "string", - "description": "Merge method to use. Possible values are `merge`, `squash` or `rebase`. Default is `merge`.", + "description": "The merge method to use.", "enum": [ "merge", "squash", @@ -34297,6 +34306,14 @@ ] } } + }, + "examples": { + "response-if-merge-was-successful": { + "value": { + "commit_title": "Expand enum", + "commit_message": "Add a new value to the merge_method enum" + } + } } } } @@ -37306,6 +37323,14 @@ "description": "Determines if all notifications should be blocked from this repository." } } + }, + "examples": { + "default": { + "value": { + "subscribed": true, + "ignored": false + } + } } } } @@ -42486,6 +42511,17 @@ "name" ], "type": "object" + }, + "examples": { + "default": { + "value": { + "name": "Hello-World", + "description": "This is your first repo!", + "homepage": "https://github.com", + "private": false, + "is_template": true + } + } } } } diff --git a/descriptions/github.ae/github.ae.yaml b/descriptions/github.ae/github.ae.yaml index ffbff82818..0094cdfea0 100644 --- a/descriptions/github.ae/github.ae.yaml +++ b/descriptions/github.ae/github.ae.yaml @@ -18820,6 +18820,12 @@ paths: type: string description: Optional parameter to specify the organization name if forking into an organization. + examples: + default: + value: + organization: octocat + name: Hello-World + default_branch_only: true responses: '202': description: Response @@ -24544,12 +24550,16 @@ paths: description: SHA that pull request head must match to allow merge. merge_method: type: string - description: Merge method to use. Possible values are `merge`, `squash` - or `rebase`. Default is `merge`. + description: The merge method to use. enum: - merge - squash - rebase + examples: + response-if-merge-was-successful: + value: + commit_title: Expand enum + commit_message: Add a new value to the merge_method enum responses: '200': description: if merge was successful @@ -26603,6 +26613,11 @@ paths: type: boolean description: Determines if all notifications should be blocked from this repository. + examples: + default: + value: + subscribed: true + ignored: false responses: '200': description: Response @@ -30433,6 +30448,14 @@ paths: required: - name type: object + examples: + default: + value: + name: Hello-World + description: This is your first repo! + homepage: https://github.com + private: false + is_template: true responses: '201': description: Response