openapi: 3.0.1
info:
  title: Equinix API Authentication Users API
  description: 'Equinix APIs use the OAuth 2.0 for authentication and authorization. Equinix supports the resource owner password and the client credentials flow.

    To begin, obtain OAuth 2.0 client credentials from the Equinix Developer Console under "My Apps". Then your client application  requests an access token from the Equinix API Authorization endpoint, extracts the access_token from the response, and sends the Bearer token to the API that you want to access'
  termsOfService: https://www.equinix.com/about/legal/terms
  contact:
    name: Equinix API Support
    url: https://docs.equinix.com/api-support.htm
  version: '1.2'
servers:
- url: https://api.equinix.com
tags:
- description: 'User Management

    '
  externalDocs:
    url: https://metal.equinix.com/developers/docs/accounts/users/
  name: Users
paths:
  /invitations:
    get:
      description: Returns all invitations in current user.
      operationId: findInvitations
      parameters:
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: Page to return
        in: query
        name: page
        schema:
          default: 1
          format: int32
          maximum: 100000
          minimum: 1
          type: integer
      - description: Items returned per page
        in: query
        name: per_page
        schema:
          default: 10
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationList'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Retrieve current user invitations
      tags:
      - Users
  /user:
    get:
      description: Returns the user object for the currently logged-in user.
      operationId: findCurrentUser
      parameters:
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
      summary: Retrieve the current user
      tags:
      - Users
    put:
      description: Updates the currently logged-in user.
      operationId: updateCurrentUser
      parameters:
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateInput'
        description: User to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Update the current user
      tags:
      - Users
  /users:
    get:
      description: Returns a list of users that the are accessible to the current user (all users in the current user’s projects, essentially).
      operationId: findUsers
      parameters:
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      - description: Page to return
        in: query
        name: page
        schema:
          default: 1
          format: int32
          maximum: 100000
          minimum: 1
          type: integer
      - description: Items returned per page
        in: query
        name: per_page
        schema:
          default: 10
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
      summary: Retrieve all users
      tags:
      - Users
      x-equinix-metal-paginated-property: Users
    post:
      description: Creates a user.
      operationId: createUser
      parameters:
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateInput'
        description: User to create
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '422':
          content:
            application/json:
              example:
                errors:
                - Email address username@example.com has already been taken
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Create a user
      tags:
      - Users
  /users/{id}:
    get:
      description: Returns a single user if the user has access
      operationId: findUserById
      parameters:
      - description: User UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'Nested attributes to exclude. Excluded objects will return only the href

          attribute. Attribute names can be dotted (up to 3 levels) to exclude deeply

          nested objects.'
        explode: false
        in: query
        name: exclude
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Retrieve a user
      tags:
      - Users
  /users/{id}/customdata:
    get:
      description: Provides the custom metadata stored for this user in json format
      operationId: findUserCustomdata
      parameters:
      - description: User UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Retrieve the custom metadata of a user
      tags:
      - Users
components:
  schemas:
    Membership:
      example:
        updated_at: 2000-01-23 04:56:07+00:00
        roles:
        - roles
        - roles
        created_at: 2000-01-23 04:56:07+00:00
        project:
          href: href
        href: href
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        user:
          href: href
      properties:
        created_at:
          format: date-time
          type: string
        href:
          type: string
        id:
          format: uuid
          type: string
        project:
          $ref: '#/components/schemas/Href'
        roles:
          items:
            type: string
          type: array
        updated_at:
          format: date-time
          type: string
        user:
          $ref: '#/components/schemas/Href'
      type: object
    User:
      example:
        avatar_thumb_url: avatar_thumb_url
        last_login_at: 2000-01-23 04:56:07+00:00
        max_projects: 2
        timezone: timezone
        default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        created_at: 2000-01-23 04:56:07+00:00
        last_name: last_name
        short_id: short_id
        fraud_score: fraud_score
        emails:
        - href: href
        - href: href
        default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        full_name: full_name
        avatar_url: avatar_url
        updated_at: 2000-01-23 04:56:07+00:00
        phone_number: phone_number
        customdata: '{}'
        href: href
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        first_name: first_name
        max_organizations: 3
        two_factor_auth: two_factor_auth
        email: email
      properties:
        avatar_thumb_url:
          type: string
        avatar_url:
          type: string
        created_at:
          format: date-time
          type: string
        customdata:
          type: object
        default_organization_id:
          format: uuid
          type: string
        default_project_id:
          format: uuid
          type: string
        email:
          type: string
        emails:
          items:
            $ref: '#/components/schemas/Href'
          type: array
        first_name:
          type: string
        fraud_score:
          type: string
        full_name:
          type: string
        href:
          type: string
        id:
          format: uuid
          type: string
        last_login_at:
          format: date-time
          type: string
        last_name:
          type: string
        max_organizations:
          type: integer
        max_projects:
          type: integer
        phone_number:
          type: string
        short_id:
          type: string
        timezone:
          type: string
        two_factor_auth:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    UserCreateInput:
      example:
        invitation_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        level: level
        timezone: timezone
        last_name: last_name
        avatar: ''
        title: title
        nonce: nonce
        emails:
        - default: true
          address: address
        - default: true
          address: address
        social_accounts: '{}'
        password: password
        verified_at: 2000-01-23 04:56:07+00:00
        company_name: company_name
        company_url: company_url
        phone_number: phone_number
        customdata: '{}'
        first_name: first_name
        two_factor_auth: two_factor_auth
      properties:
        avatar:
          format: binary
          type: string
        company_name:
          type: string
        company_url:
          type: string
        customdata:
          type: object
        emails:
          items:
            $ref: '#/components/schemas/EmailInput'
          type: array
        first_name:
          type: string
        last_name:
          type: string
        level:
          type: string
        password:
          type: string
        phone_number:
          type: string
        social_accounts:
          type: object
        timezone:
          type: string
        title:
          type: string
        two_factor_auth:
          type: string
        verified_at:
          format: date-time
          type: string
        invitation_id:
          format: uuid
          type: string
        nonce:
          type: string
      required:
      - emails
      - first_name
      - last_name
      type: object
    UserUpdateInput:
      example:
        password: password
        timezone: timezone
        last_name: last_name
        phone_number: phone_number
        customdata: '{}'
        first_name: first_name
      properties:
        customdata:
          type: object
        first_name:
          type: string
        last_name:
          type: string
        password:
          type: string
        phone_number:
          type: string
        timezone:
          type: string
      type: object
    Meta:
      example:
        next:
          href: href
        total: 0
        last:
          href: href
        previous:
          href: href
        last_page: 1
        self:
          href: href
        first:
          href: href
        current_page: 6
      properties:
        first:
          $ref: '#/components/schemas/Href'
        last:
          $ref: '#/components/schemas/Href'
        next:
          $ref: '#/components/schemas/Href'
        previous:
          $ref: '#/components/schemas/Href'
        self:
          $ref: '#/components/schemas/Href'
        total:
          type: integer
        current_page:
          type: integer
        last_page:
          type: integer
      type: object
    Error:
      description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
      properties:
        error:
          description: A description of the error that caused the request to fail.
          type: string
        errors:
          description: A list of errors that contributed to the request failing.
          items:
            description: An error message that contributed to the request failing.
            type: string
          type: array
      type: object
    InvitationList:
      example:
        invitations:
        - updated_at: 2000-01-23 04:56:07+00:00
          roles:
          - roles
          - roles
          created_at: 2000-01-23 04:56:07+00:00
          project:
            href: href
          href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          user:
            href: href
        - updated_at: 2000-01-23 04:56:07+00:00
          roles:
          - roles
          - roles
          created_at: 2000-01-23 04:56:07+00:00
          project:
            href: href
          href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          user:
            href: href
      properties:
        invitations:
          items:
            $ref: '#/components/schemas/Membership'
          type: array
      type: object
    EmailInput:
      example:
        default: true
        address: address
      properties:
        address:
          type: string
        default:
          type: boolean
      required:
      - address
      type: object
    UserList:
      example:
        meta:
          next:
            href: href
          total: 0
          last:
            href: href
          previous:
            href: href
          last_page: 1
          self:
            href: href
          first:
            href: href
          current_page: 6
        users:
        - avatar_thumb_url: avatar_thumb_url
          last_login_at: 2000-01-23 04:56:07+00:00
          max_projects: 2
          timezone: timezone
          default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          created_at: 2000-01-23 04:56:07+00:00
          last_name: last_name
          short_id: short_id
          fraud_score: fraud_score
          emails:
          - href: href
          - href: href
          default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          full_name: full_name
          avatar_url: avatar_url
          updated_at: 2000-01-23 04:56:07+00:00
          phone_number: phone_number
          customdata: '{}'
          href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          first_name: first_name
          max_organizations: 3
          two_factor_auth: two_factor_auth
          email: email
        - avatar_thumb_url: avatar_thumb_url
          last_login_at: 2000-01-23 04:56:07+00:00
          max_projects: 2
          timezone: timezone
          default_project_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          created_at: 2000-01-23 04:56:07+00:00
          last_name: last_name
          short_id: short_id
          fraud_score: fraud_score
          emails:
          - href: href
          - href: href
          default_organization_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          full_name: full_name
          avatar_url: avatar_url
          updated_at: 2000-01-23 04:56:07+00:00
          phone_number: phone_number
          customdata: '{}'
          href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          first_name: first_name
          max_organizations: 3
          two_factor_auth: two_factor_auth
          email: email
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        users:
          items:
            $ref: '#/components/schemas/User'
          type: array
      type: object
    Href:
      example:
        href: href
      properties:
        href:
          type: string
      required:
      - href
      type: object
x-eqx-api-linter-skip-rules:
- 3
- 38