GitLab Provider identities API

openapi: 3.2.0
info:
  title: GitLab REST Provider identities API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Provider identities
  description: 'Use this API to manage the SAML and SCIM identities linked to users in a group.


    Prerequisites for the SCIM endpoints:


    - You must enable group SSO.

    - You must enable SCIM for group SSO.

    - You must authenticate with a personal access token

    or group access token that has the correct scope.


    These endpoints get, check, update, and delete SCIM identities in groups, and do not implement

    the RFC7644 protocol. They differ from the

    internal group SCIM API and the

    internal instance SCIM API,

    which implement RFC7644 for SCIM provider integration and require a SCIM token.'
  x-displayName: Provider identities
  externalDocs:
    url: https://docs.gitlab.com/api/saml/
paths:
  /api/v4/groups/{id}/saml/identities:
    get:
      operationId: getApiV4GroupsIdSamlIdentities
      summary: Retrieve SAML identities for a group
      description: Retrieves SAML identities for a group.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
  /api/v4/groups/{id}/saml/{uid}:
    get:
      operationId: getApiV4GroupsIdSamlUid
      summary: Retrieve a SAML identity
      description: Retrieves a specified SAML identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
    patch:
      operationId: patchApiV4GroupsIdSamlUid
      summary: Update `extern_uid` field for a SAML identity
      description: Updates the `extern_uid` field for a specified SAML identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchApiV4GroupsIdSamlUidRequest'
      x-gitlab-tier: premium
    delete:
      operationId: deleteApiV4GroupsIdSamlUid
      summary: Delete a SAML identity
      description: Deletes a specified SAML identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
  /api/v4/groups/{id}/scim/identities:
    get:
      operationId: getApiV4GroupsIdScimIdentities
      summary: Retrieve SCIM identities for a group
      description: Retrieves SCIM identities for a group.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
  /api/v4/groups/{id}/scim/{uid}:
    get:
      operationId: getApiV4GroupsIdScimUid
      summary: Retrieve a SCIM identity
      description: Retrieves a specified SCIM identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
    patch:
      operationId: patchApiV4GroupsIdScimUid
      summary: Update `extern_uid` field for a SCIM identity
      description: Updates the `extern_uid` field for a specified SCIM identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchApiV4GroupsIdScimUidRequest'
      x-gitlab-tier: premium
    delete:
      operationId: deleteApiV4GroupsIdScimUid
      summary: Delete a SCIM identity
      description: Deletes a specified SCIM identity.
      tags:
      - Provider identities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesIdentityDetail'
        '404':
          description: Not Found
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: uid
        required: true
        description: External UID of the user.
        schema:
          type: string
        in: path
      x-gitlab-tier: premium
components:
  schemas:
    patchApiV4GroupsIdScimUidRequest:
      type: object
      properties:
        extern_uid:
          type:
          - string
          - 'null'
          description: New external UID of the user.
      required:
      - extern_uid
    patchApiV4GroupsIdSamlUidRequest:
      type: object
      properties:
        extern_uid:
          type:
          - string
          - 'null'
          description: New external UID of the user.
      required:
      - extern_uid
    APIEntitiesIdentityDetail:
      type: object
      properties:
        extern_uid:
          type: string
        user_id:
          type: string
        active:
          type: string
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header