Vendasta user API

openapi: 3.2.0
info:
  title: Vendasta User API
  version: '1.0'
  description: 'Operations tagged User across 2 of this provider''s published API definitions: vendasta-scim-openapi.yml, vendasta-user-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://prod.apigateway.co/scim
  description: Production
- url: https://demo.apigateway.co/scim
  description: Demo
- url: http://localhost:11001/scim
  description: Local
- url: '{local}/scim'
  description: Localhost
- url: https://developers.vendasta.com/api/v1
  description: Production Server
- url: https://developers-demo.vendasta.com/api/v1
  description: Demo Server
tags:
- name: User
  description: User resources
paths:
  /{namespace}/Users:
    parameters:
    - $ref: '#/components/parameters/namespace'
    get:
      tags:
      - User
      summary: Search Users
      parameters:
      - $ref: '#/components/parameters/accept-scim'
      - $ref: '#/components/parameters/accept-charset-scim'
      - name: filter
        in: query
        description: 'Filtering is an OPTIONAL parameter.

          List users using described filters.

          <br> Supported filters are:

          <br> `externalId eq "user_external_id"`

          <br> `userName eq "user@mail.com"`

          <br>`/scim/v1/{partnerid}/Users?filter=userName eq "user@mail.com"`'
        schema:
          type: string
      - schema:
          type: string
        in: query
        name: attributes
        description: 'Resource attributes can be restriceted by using attributes parameter.

          <br>`/scim/v1/{partnerid}/Users?filter=userName eq "user@mail.com"&attributes=userName`

          <br>`/scim/v1/{partnerid}/Users?attributes=id,externalId,userName`'
      - schema:
          type: string
        in: query
        name: excludedAttributes
        description: 'A list of the attributes not to return in the response body. It '
      - schema:
          type: integer
          minimum: 1
          default: 1
        in: query
        name: startIndex
        description: The 1-based index of the first query result
      - schema:
          type: integer
        in: query
        name: count
        description: Specifies the desired maximum number of query results per page
      - schema:
          type: string
          enum:
          - userName
          - meta.created
          - name. givenName
          - name.familyName
        in: query
        name: sortBy
        description: The attribute to order the results based on
      - schema:
          type: string
          enum:
          - ascending
          - descending
          default: ascending
        in: query
        name: sortOrder
        description: Specifies if the results should be sorted A-Z (ascending) or Z-A (descending) based on the attribute in the sortBy parameter
      responses:
        '200':
          description: OK
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/ListResponseUsers'
        '400':
          description: 'Below are the error messages for bad request:

            <br>Only eq filter operator supported.

            <br>Only "userName" or "externalId" filter attribute supported.

            <br>There is some issue with provided attribute value.

            '
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        This endpoint can be used to search users based on filter or list all user if filter criteria is ignored'
      operationId: scim-search-users
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    post:
      tags:
      - User
      summary: Create User
      requestBody:
        description: Create a new user
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Failed to create user.
        '409':
          description: One or more of the attribute values are already in use or are reserved.
      operationId: scim-create-user
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        Create User based on SCIM schema'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    servers:
    - url: https://prod.apigateway.co/scim
      description: Production
    - url: https://demo.apigateway.co/scim
      description: Demo
    - url: http://localhost:11001/scim
      description: Local
    - url: '{local}/scim'
      description: Localhost
  /{namespace}/Users/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
      description: The id of the user assigned by Vendasta
    - $ref: '#/components/parameters/namespace'
    get:
      tags:
      - User
      summary: Get User
      responses:
        '200':
          description: OK
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Resource not found
      x-internal: false
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        Get an user when the user id is known'
      operationId: scim-get-user
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    put:
      tags:
      - User
      summary: Replace User
      requestBody:
        description: Create a new user
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Failed to create user.
      operationId: scim-replace-user
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        API to replace an user. All of the attributes will be replaced with provided value and attributes will be kept blank for which no value is specified'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    patch:
      tags:
      - User
      summary: Update User
      requestBody:
        content:
          application/scim+json:
            schema:
              $ref: '#/components/schemas/PatchOp'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/User'
        '405':
          description: Invalid input
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        Update an user''s one or multiple attributes by providing operation path and value. Post update all other attributes will be unchanged apart from provided attributes.'
      operationId: scim-update-user
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    delete:
      tags:
      - User
      summary: Delete User
      responses:
        '204':
          description: No Content
        '405':
          description: Resource not found
      operationId: scim-delete-user
      x-lifecycle:
        status: proposed
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        API to delete an user'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    servers:
    - url: https://prod.apigateway.co/scim
      description: Production
    - url: https://demo.apigateway.co/scim
      description: Demo
    - url: http://localhost:11001/scim
      description: Local
    - url: '{local}/scim'
      description: Localhost
  /{namespace}/Me:
    parameters:
    - $ref: '#/components/parameters/namespace'
    get:
      summary: Me redirect
      tags:
      - User
      responses:
        '308':
          description: Permanent Redirect (experiemental)
          headers:
            Location:
              schema:
                type: string
                example: https://prod.apigateway.co/scim/VUNI/Users/U-123456
              description: The correct URI to make a request to
      operationId: get-namespace-Me
      x-lifecycle:
        status: proposed
      description: "[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`\n\n\nThe SCIM standard defines a special resource called \"Me\" that represents the user making the API request as identified by the access token. This is similar to the \"/userinfo\" endpoint defined in the OAuth2 spec. \n\nThe Vendasta platform will respond to all requests with a redirect to the coorisponding '/Users' endpoint. This may result in a different namespace."
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
    servers:
    - url: https://prod.apigateway.co/scim
      description: Production
    - url: https://demo.apigateway.co/scim
      description: Demo
    - url: http://localhost:11001/scim
      description: Local
    - url: '{local}/scim'
      description: Localhost
  /user/{user_id}:
    get:
      tags:
      - User
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  took:
                    type: integer
                    description: The total response time, in milliseconds.
                  data:
                    $ref: '#/components/schemas/user'
        '401':
          description: Invalid Authentication
        '403':
          description: Not authorized to access user.
        '404':
          description: User not found
      parameters:
      - required: true
        description: A unique user ID that can be used to identify and reference a user.
        in: path
        name: user_id
        schema:
          type: string
      summary: Get User
      security:
      - BearerAuth: []
    servers:
    - url: https://developers.vendasta.com/api/v1
      description: Production Server
    - url: https://developers-demo.vendasta.com/api/v1
      description: Demo Server
  /user/{user_id}/permissions/{account_id}:
    head:
      tags:
      - User
      responses:
        '200':
          description: User has permissions to the given account.
        '401':
          description: Invalid Authentication
        '403':
          description: User does not have permission to the account.
        '404':
          description: Account not found.
      parameters:
      - required: true
        description: A unique user ID that can be used to identify and reference a user.
        in: path
        name: user_id
        schema:
          type: string
      - required: true
        description: A unique account ID that can be used to identify and reference an account.
        in: path
        name: account_id
        schema:
          type: string
      summary: Check User Access to an Account
      security:
      - BearerAuth: []
    servers:
    - url: https://developers.vendasta.com/api/v1
      description: Production Server
    - url: https://developers-demo.vendasta.com/api/v1
      description: Demo Server
components:
  schemas:
    Email:
      type: object
      properties:
        value:
          type: string
          format: email
          example: bjensen@example.com
        type:
          type: string
          example: work
        primary:
          type: boolean
    ListResponseUsers:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/User'
        startIndex:
          type: number
          description: 'The 1-based index of the first result in the current set of list results.

            REQUIRED when partial results are returned due to pagination.'
        itemsPerPage:
          type: number
          description: 'The number of resources returned in a list response page.

            REQUIRED when partial results are returned due to pagination.'
        totalResults:
          type: number
          description: The total number of results returned by the list or query operation
    PatchOp:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          example:
          - urn:ietf:params:scim:api:messages:2.0:PatchOp
        Operations:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
    Operation:
      type: object
      properties:
        op:
          type: string
          example: Replace
        path:
          type: string
          example: emails[type eq "work"].value
        value:
          type: string
          example: updatedEmail@mail.com
    Address:
      type: object
      properties:
        type:
          type: string
          example: work
        streetAddress:
          type: string
          example: 100 Universal City Plaza
        locality:
          type: string
          example: Hollywood
          x-stoplight:
            id: ho5pd2iv86rrw
        region:
          type: string
          pattern: ^[A-Z]{2}-[\w]{1,3}$
          description: 'The code for the top level subdivision within the country (state/province). For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)


            Examples: CA-SK, US-FL, AG-08, AU-NSW'
          example: CA-SK
        postalCode:
          type: string
          example: '91608'
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: 'The two letter country code. For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)


            Examples: CA, US, AU'
          example: CA
        formatted:
          type: string
          example: 100 Universal City Plaza\nHollywood, CA-SK 91608 CA
        primary:
          type: boolean
    User:
      type: object
      properties:
        schemas:
          type: array
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
          minItems: 1
          uniqueItems: true
          items:
            type: string
            example: '["urn:ietf:params:scim:schemas:core:2.0:User"]'
        id:
          type: string
          description: 'Unique identifier in Vendasta.

            This field will be generated by Vendasta during creation of user.'
        externalId:
          type: string
          description: External unique identifier of the user.
        userName:
          type: string
          description: 'A service provider''s unique identifier for the user, typically

            used by the user to directly authenticate to the service provider.

            Often displayed to the user as their unique identifier within the

            system (as opposed to "id" or "externalId", which are generally

            opaque and not user-friendly identifiers).  Each User MUST include

            a non-empty userName value.  This identifier MUST be unique across

            the service provider''s entire set of Users.  This attribute is

            REQUIRED and is case insensitive.

            <br><b>userName</b> is mapped with <b>email</b>'
          example: barbara@mail.com
        name:
          $ref: '#/components/schemas/Name'
        displayName:
          type: string
          description: givenName + familyName
          example: Babs Jensen
          readOnly: true
        nickName:
          type: string
          example: Babs
        profileUrl:
          type: string
          format: uri
          description: <b>This field currently NOT SUPPORTED</b>
        title:
          type: string
          description: 'The user''''s title, such as "Vice President".

            <br><b>This field currently NOT SUPPORTED</b>'
        userType:
          type: string
          description: 'Used to identify the relationship between the organization and the

            user.  Typical values used might be "Contractor", "Employee",

            "Intern", "Temp", "External", and "Unknown", but any value may be used.

            <br><b>This field currently NOT SUPPORTED</b>'
        preferredLanguage:
          type: string
        locale:
          type: string
          description: <b>This field currently NOT SUPPORTED</b>
        timezone:
          type: string
          example: America/Regina
        emails:
          type: array
          minItems: 1
          maxItems: 1
          description: Email is i one to one mapping with user.
          items:
            $ref: '#/components/schemas/Email'
        active:
          type: boolean
        password:
          type: string
          description: <b>This field currently NOT SUPPORTED</b>
        addresses:
          type: array
          description: Address is in one to one mapping with user
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/Address'
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - schemas
      - userName
      - name
      - emails
    Member:
      type: object
      properties:
        value:
          type: string
          example: 2819c223-7f76-453a-919d-413861904646
        $ref:
          type: string
          format: uri
          example: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
        display:
          type: string
          example: Babs Jensen
    PhoneNumber:
      type: object
      properties:
        value:
          type: string
          example: +1-306-555-1234
          description: phone number format should match the region / country given in address against the type
        type:
          type: string
          example: work
    Name:
      type: object
      properties:
        formatted:
          type: string
          description: givenName + " " + familyName
          readOnly: true
        familyName:
          type: string
          example: Jensen
        givenName:
          type: string
          example: Barbara
        middleName:
          type: string
          example: Jane
          description: <b>This field currently NOT SUPPORTED</b>
        honorificPrefix:
          type: string
          example: Ms.
          description: <b>This field currently NOT SUPPORTED</b>
        honorificSuffix:
          type: string
          example: III
          description: <b>This field currently NOT SUPPORTED</b>
      required:
      - givenName
    Meta:
      type: object
      properties:
        resourceType:
          type: string
          example: User
        created:
          type: string
          format: date-time
          example: '2010-01-23T04:56:22Z'
        lastModified:
          type: string
          format: date-time
          example: '2011-05-13T04:42:34Z'
        version:
          type: string
          description: 'The version of the resource being returned.  This value

            must be the same as the entity-tag (ETag) HTTP response header.

            This attribute has "caseExact" as "true".  Service provider support for this

            attribute is optional and subject to the service provider''s

            support for versioning.  If a

            service provider provides "version" (entity-tag) for a

            representation and the generation of that entity-tag does not

            satisfy all of the characteristics of a strong validator, then the origin server MUST mark the

            "version" (entity-tag) as weak by prefixing its opaque value

            with "W/" (case sensitive).'
          example: W/"3694e05e9dff591"
        location:
          type: string
          example: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
    user:
      required:
      - id
      - partner_id
      properties:
        first_name:
          type: string
        last_name:
          type: string
        work_phone:
          type: string
        email:
          type: string
        email_verified:
          type: boolean
        accounts:
          items:
            type: string
          type: array
        partner_id:
          type: string
        id:
          type: string
      type: object
  parameters:
    namespace:
      name: namespace
      in: path
      required: true
      schema:
        type: string
        example: VUNI
      description: Currently this must be the id of the partner that you wish to manage users for. In the future we plan to support other types of namespaces such as marketplace apps
    accept-scim:
      name: Accept
      in: header
      schema:
        type: string
        default: application/scim+json
        enum:
        - application/scim+json
        - application/json
        example: application/scim+json
      description: Indicates that the response body contains content formated according to SCIM rules
    accept-charset-scim:
      name: Accept-Charset
      in: header
      schema:
        type: string
        default: UTF-8
        enum:
        - UTF-8
        example: UTF-8
      description: Indicates that the response body contains content in UTF-8
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: ''
    OAuth2Demo:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-demo.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-demo.apigateway.co/oauth2/token
          scopes:
            user.admin: Read-write access to manage all users
            user.profile:read: Read access to the profile fields of all categories of users
    OAuth2Prod:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
          scopes:
            user.admin: Read-write access to manage all users
            user.profile:read: Read access to the profile fields of all categories of users
    BearerAuth:
      type: http
      scheme: bearer
x-refined-from:
- vendasta-scim-openapi.yml
- vendasta-user-api-openapi.yml