Talend SCIM 2.0 User Management API

openapi: 3.2.0
info:
  title: SCIM v2 SCIM 2.0 User Management API
  description: Manage your users and groups using SCIM 2.0.
  contact:
    name: Talend Support
  license:
    name: Apache License Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  version: 2021-03
servers:
- url: https://api.eu.cloud.talend.com
  description: URL for the AWS Europe region
  x-talend:
    isPublished: true
- url: https://api.ap.cloud.talend.com
  description: URL for the AWS Asia Pacific region
  x-talend:
    isPublished: true
- url: https://api.us.cloud.talend.com
  description: URL for the AWS United States East region
  x-talend:
    isPublished: true
- url: https://api.au.cloud.talend.com
  description: URL for the AWS Australia region
  x-talend:
    isPublished: true
- url: https://api.us-west.cloud.talend.com
  description: URL for the Azure United States West region
  x-talend:
    isPublished: true
security:
- Public: []
tags:
- name: SCIM 2.0 User Management
paths:
  /scim/v2/Users:
    summary: Operations on users
    description: "As you might expect, users map to the individuals of your account (domain). Each user contains properties called attributes. You can list users, filter by attribute, add new users, update a user's profile information, or remove a user entirely.\n\nAttributes are the details associated with a user's account. These are the details that someone would typically set in their profile. The following table maps SCIM attributes with Talend Cloud user attributes:\n\n| Talend user field | SCIM attribute | Attribute type |Required|\n| -------- | -------- | -------- | -------- |\n| login     | userName     | Singular     | **Required** |\n| firstName     | name.givenName     | Singular     | **Required** |\n| middleName     | name.middleName     | Singular     | |\n| lastName     | name.familyName     | Singular     | **Required** |\n| email     | \temails\\[primary=true\\].value     | Multi-Valued     | |\n| phone     | phoneNumbers\\[type='work'\\].value     | Multi-Valued     | |\n| active     | active     | Singular     | |\n| password     | password     | Singular     | |\n| title     | title     | Singular     | |\n| preferredLanguage     | preferredLanguage     | Singular   |   |\n| timezone     | timezone     | Singular     | |\n| groups     | groups     | Multi-Valued     | |\n| roles     | roles     | Multi-Valued     | |\n\nRequires the permission **Users - Manage** (**TMC_USER_MANAGEMENT**).\n"
    x-talend:
      section: Users
    get:
      tags:
      - SCIM 2.0 User Management
      summary: Get users
      description: 'Returns a paginated list of users, 100 user per page by default. `count` and `startIndex` parameters can be updated to get larger pages or to retrive other pages.


        It is possible to use `filter` parameter to return a list of specific users (see SCIMv2 specification for details).


        It is also possible to sort the results using the parameters `sortBy` and `sortOrder`. The attributes `attributes` and `excludedAttributes` can be set to select or exclude specific attributes.'
      operationId: getAll
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
      - name: startIndex
        in: query
        schema:
          type: integer
          format: int32
          default: 1
      - name: count
        in: query
        schema:
          type: integer
          format: int32
          default: 100
      - name: sortOrder
        in: query
        schema:
          type: string
      - name: sortBy
        in: query
        schema:
          type: string
      - name: filter
        in: query
        schema:
          type: string
      - name: excludedAttributes
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ListResponseGenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    post:
      tags:
      - SCIM 2.0 User Management
      summary: Create a new user
      description: 'Create and retrieve a user resource.

        It is possible to select or exlude attributes using `attributes` and `excludedAttributes` query parameters.'
      operationId: create
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
      - name: excludedAttributes
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserResource'
      responses:
        '201':
          description: Created
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /scim/v2/Users/{id}:
    summary: Operations on a specific user
    description: "As you might expect, users map to the individuals of your account (domain). Each user contains properties called attributes. You can list users, filter by attribute, add new users, update a user's profile information, or remove a user entirely.\n\nAttributes are the details associated with a user's account. These are the details that someone would typically set in their profile. The following table maps SCIM attributes with Talend Cloud user attributes:\n\n| Talend user field | SCIM attribute | Attribute type |Required|\n| -------- | -------- | -------- | -------- |\n| login     | userName     | Singular     | **Required** |\n| firstName     | name.givenName     | Singular     | **Required** |\n| middleName     | name.middleName     | Singular     | |\n| lastName     | name.familyName     | Singular     | **Required** |\n| email     | \temails\\[primary=true\\].value     | Multi-Valued     | |\n| phone     | phoneNumbers\\[type='work'\\].value     | Multi-Valued     | |\n| active     | active     | Singular     | |\n| password     | password     | Singular     | |\n| title     | title     | Singular     | |\n| preferredLanguage     | preferredLanguage     | Singular   |   |\n| timezone     | timezone     | Singular     | |\n| groups     | groups     | Multi-Valued     | |\n| roles     | roles     | Multi-Valued     | |\n\nRequires the permission **Users - Manage** (**TMC_USER_MANAGEMENT**)."
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    x-talend:
      section: Users
    get:
      tags:
      - SCIM 2.0 User Management
      summary: Get specific user
      description: 'Retrieve a single user resource. The value of the {id} should be a UUID.

        It is possible to select or exlude attributes using `attributes` and `excludedAttributes` query parameters.'
      operationId: get
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
      - name: excludedAttributes
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    put:
      tags:
      - SCIM 2.0 User Management
      summary: Update specific user
      description: 'Update and return a single user resource. The value of the {id} should be a UUID.

        It is possible to select or exlude attributes using `attributes` and `excludedAttributes` query parameters.'
      operationId: update
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
      - name: excludedAttributes
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserResource'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      tags:
      - SCIM 2.0 User Management
      summary: Delete specific user
      description: Delete a single user resource. The value of the {id} should be a UUID.
      operationId: delete
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    patch:
      tags:
      - SCIM 2.0 User Management
      summary: Update partially specific user
      description: 'Update partially and retrieve a single user resource. The value of the {id} should be a UUID.

        It is possible to select or exlude attributes using `attributes` and `excludedAttributes` query parameters.'
      operationId: patch
      parameters:
      - name: attributes
        in: query
        schema:
          type: string
      - name: excludedAttributes
        in: query
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /scim/v2/Users/.search:
    description: Requires the permission **Users - Manage** (**TMC_USER_MANAGEMENT**).
    x-talend:
      section: Users
    post:
      tags:
      - SCIM 2.0 User Management
      summary: Search users
      description: 'Returns a paginated list of users, 100 user per page by default. `count` and `startIndex` parameters can be updated to get larger pages or to retrive other pages.


        It is possible to use `filter` parameter to return a list of specific users (see SCIMv2 specification for details).


        It is also possible to sort the results using the parameters `sortBy` and `sortOrder`. The attributes `attributes` and `excludedAttributes` can be set to select or exclude specific attributes.'
      operationId: search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example: "{\n  \"schemas\": [\n    \"urn:ietf:params:scim:api:messages:2.0:SearchRequest\"\n  ],\n  \"attributes\": [\n    \"name.givenName\"\n  ],\n  \"filter\": \"username sw \\\"coco\\\"\",\n  \"sortBy\": \"username\",\n  \"sortOrder\": \"ascending\",\n  \"startIndex\": 1,\n  \"count\": 10\n}"
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ListResponseGenericScimResource'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
components:
  schemas:
    GenericScimResource:
      type: object
      properties:
        objectNode:
          type: object
        id:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        externalId:
          type: string
        schemaUrns:
          type: array
          items:
            type: string
      x-talend:
        section: Common
    PatchRequest:
      type: object
      required:
      - Operations
      properties:
        schemas:
          type: array
          items:
            type: string
          uniqueItems: true
        id:
          type: string
        externalId:
          type: string
        Operations:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/AddOperation'
            - $ref: '#/components/schemas/RemoveOperation'
            - $ref: '#/components/schemas/ReplaceOperation'
        meta:
          $ref: '#/components/schemas/Meta'
      x-talend:
        section: Common
    Meta:
      type: object
      properties:
        resourceType:
          type: string
        created:
          type: string
          format: date-time
        lastModified:
          type: string
          format: date-time
        location:
          type: string
        version:
          type: string
      x-talend:
        section: Common
    PhoneNumber:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    ListResponseGenericScimResource:
      type: object
      required:
      - Resources
      - totalResults
      properties:
        schemas:
          type: array
          items:
            type: string
          uniqueItems: true
        id:
          type: string
        externalId:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        totalResults:
          type: integer
          format: int64
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/GenericScimResource'
        startIndex:
          type: integer
          format: int32
        itemsPerPage:
          type: integer
          format: int32
      x-talend:
        section: Common
    AddOperation:
      allOf:
      - $ref: '#/components/schemas/PatchOperation'
      - type: object
        properties:
          value:
            $ref: '#/components/schemas/JsonNode'
      x-talend:
        section: Common
    InstantMessagingAddress:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    JsonNode:
      type: object
      x-talend:
        section: Common
    Address:
      type: object
      properties:
        formatted:
          type: string
        streetAddress:
          type: string
        locality:
          type: string
        region:
          type: string
        postalCode:
          type: string
        country:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    SearchRequest:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          uniqueItems: true
        id:
          type: string
        externalId:
          type: string
        attributes:
          type: array
          items:
            type: string
          uniqueItems: true
        excludedAttributes:
          type: array
          items:
            type: string
          uniqueItems: true
        filter:
          type: string
        sortBy:
          type: string
        sortOrder:
          type: string
          enum:
          - ascending
          - descending
        startIndex:
          type: integer
          format: int32
        count:
          type: integer
          format: int32
        meta:
          $ref: '#/components/schemas/Meta'
      x-talend:
        section: Common
    PatchOperation:
      type: object
      required:
      - op
      properties:
        path:
          type: string
        op:
          type: string
      x-talend:
        section: Common
    Entitlement:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    Role:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    Group:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        $ref:
          type: string
      x-talend:
        section: Users
    Name:
      type: object
      properties:
        formatted:
          type: string
        familyName:
          type: string
        givenName:
          type: string
        middleName:
          type: string
        honorificPrefix:
          type: string
        honorificSuffix:
          type: string
      x-talend:
        section: Users
    X509Certificate:
      type: object
      properties:
        value:
          type: array
          items:
            type: string
            format: binary
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    UserResource:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          uniqueItems: true
        id:
          type: string
        externalId:
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
        userName:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        displayName:
          type: string
        nickName:
          type: string
        profileUrl:
          type: string
        title:
          type: string
        userType:
          type: string
        preferredLanguage:
          type: string
        locale:
          type: string
        timezone:
          type: string
        active:
          type: boolean
        password:
          type: string
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        ims:
          type: array
          items:
            $ref: '#/components/schemas/InstantMessagingAddress'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Group'
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/Entitlement'
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        x509Certificates:
          type: array
          items:
            $ref: '#/components/schemas/X509Certificate'
      x-talend:
        section: Users
    Photo:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    Email:
      type: object
      properties:
        value:
          type: string
        display:
          type: string
        type:
          type: string
        primary:
          type: boolean
      x-talend:
        section: Users
    RemoveOperation:
      allOf:
      - $ref: '#/components/schemas/PatchOperation'
      - type: object
        properties:
          value:
            $ref: '#/components/schemas/JsonNode'
      x-talend:
        section: Common
    ReplaceOperation:
      allOf:
      - $ref: '#/components/schemas/PatchOperation'
      - type: object
        properties:
          value:
            $ref: '#/components/schemas/JsonNode'
      x-talend:
        section: Common
  responses:
    500InternalServerError:
      description: The server encountered an unexpected condition that prevented it from fulfilling the request.
    404NotFound:
      description: Resource not found.
    401Unauthorized:
      description: The system failed to authenticate the user. Either the Authorization header was missing or the provided token was incorrect.
    403Forbidden:
      description: The system failed to authorize the user. The provided token was recognized but did not have the rights to perform the action. Contact your security administrator to get the appropriate rights.
    429TooManyRequests:
      description: Too many requests were sent. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
    400BadRequest:
      description: Invalid request body. The message varies depending on the cause of the bad request. For example, the cause could be a malformed body or parameter.
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: Bearer <TOKEN>
x-talend:
  sections:
    Discovery: {}
    Users:
      description: "As you might expect, users map to the individuals of your account (domain). Each user contains properties called attributes. You can list users, filter by attribute, add new users, update a user's profile information, or remove a user entirely.\n\nAttributes are the details associated with a user's account. These are the details that someone would typically set in their profile. The following table maps SCIM attributes with Talend Cloud user attributes:\n\n| Talend user field | SCIM attribute | Attribute type |Required|\n| -------- | -------- | -------- | -------- |\n| login     | userName     | Singular     | **Required** |\n| firstName     | name.givenName     | Singular     | **Required** |\n| middleName     | name.middleName     | Singular     | |\n| lastName     | name.familyName     | Singular     | **Required** |\n| email     | \temails\\[primary=true\\].value     | Multi-Valued     | |\n| phone     | phoneNumbers\\[type='work'\\].value     | Multi-Valued     | |\n| active     | active     | Singular     | |\n| password     | password     | Singular     | |\n| title     | title     | Singular     | |\n| preferredLanguage     | preferredLanguage     | Singular   |   |\n| timezone     | timezone     | Singular     | |\n| groups     | groups     | Multi-Valued     | |\n| roles     | roles     | Multi-Valued     | |\n\nRequires the permission **Users - Manage** (**TMC_USER_MANAGEMENT**)."
    Groups:
      description: 'Groups map to Talend groups with the following attributes:

        | Talend user field | SCIM attribute | Attribute type |Required|

        | -------- | -------- | -------- | -------- |

        | name     | displayName     | Singular     | **Required** |

        | userIds     | members.value     | Multi-Valued     | |


        Requires the permission **Groups - Manage** (**TMC_GROUP_MANAGEMENT**).'
    Roles:
      description: 'Roles map to Talend roles with the following attributes:

        | Talend user field | SCIM attribute | Attribute type |Required|

        | -------- | -------- | -------- | -------- |

        | name     | name     | Singular     | **Required** |

        | permissions     | entitlements     | Multi-Valued     | **Required**|


        Requires the permission **Roles - Manage** (**TMC_ROLE_MANAGEMENT**).'
    Common: {}