Pure Storage Authorization API

openapi: 3.2.0
info:
  title: FlashArray REST Active Directory Authorization API
  version: '2.52'
  description: 'Active Directory configuration authenticates users for NFS using Kerberos or SMB using Kerberos

    or New Technology LAN Manager (NTLM). Active Directory is also used to authorize users by

    mapping identities across the NFS and SMB protocols by using LDAP queries.

    '
servers:
- url: /
tags:
- name: Authorization
  description: 'Pure Storage uses the OAuth 2.0 Token Exchange authorization grant and JSON Web Tokens (JWTs)

    to authenticate to the Pure Storage REST API.

    Before you can exchange the ID token for an access token, create and enable the API client

    to generate the `key_id`, `id`, and `issuer` values.

    These values will be used as JWT claims for the `subject_token` parameter.

    '
paths:
  /oauth2/1.0/token:
    post:
      tags:
      - Authorization
      summary: Pure Storage Get Access Token
      description: 'Exchanges an ID Token for an OAuth 2.0 access token.

        '
      parameters:
      - name: X-Request-ID
        in: header
        description: 'Supplied by client during request or generated by server.

          '
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - grant_type
              - subject_token
              - subject_token_type
              type: object
              properties:
                grant_type:
                  $ref: '#/components/schemas/OauthGrantType'
                subject_token:
                  $ref: '#/components/schemas/OauthSubjectToken'
                subject_token_type:
                  $ref: '#/components/schemas/OauthSubjectTokenType'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/OauthToken200'
        '400':
          $ref: '#/components/responses/OauthToken400'
        '401':
          $ref: '#/components/responses/OauthToken401'
      security: []
  /api/api_version:
    get:
      tags:
      - Authorization
      summary: Pure Storage List Available API Versions
      description: 'Returns a list of available API versions. No authentication is required to access this endpoint.

        '
      parameters:
      - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api_versionResponse'
      security: []
  /api/2.52/login:
    post:
      tags:
      - Authorization
      summary: Pure Storage Create a User Session
      description: 'Creates a user session and returns a session token, using either the user''s API token or

        their username and password. `api-token` is passed in a header, with the request

        body empty. Otherwise `username` and `password` are passed in the request body,

        without an `api-token` header.


        Storing user passwords client-side is not recommended. The username-password

        authentication option should only be used as necessary for initial retrieval of

        an API token, which should be securely stored and used for all subsequent logins.

        '
      parameters:
      - name: api-token
        in: header
        description: 'API token for a user.

          '
        schema:
          type: string
        example: 0f2e2884-9486-c6c2-438c-f50418f2aac3
      - $ref: '#/components/parameters/XRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginPost'
        required: false
        x-codegen-request-body-name: login
      responses:
        '200':
          description: OK
          headers:
            x-auth-token:
              description: Session token for a user.
              schema:
                type: string
                example: 3be3d489-55c6-4643-90ac-a476dbc98812
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsernameResponse'
      x-codegen-request-body-name: login
  /api/2.52/logout:
    post:
      tags:
      - Authorization
      summary: Pure Storage POST Logout (Placeholder)
      description: 'Invalidate a session token.

        '
      parameters:
      - name: x-auth-token
        in: header
        description: Session token for a user.
        schema:
          type: string
        example: 3be3d489-55c6-4643-90ac-a476dbc98812
      - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: OK
          content: {}
  /api/login:
    post:
      tags:
      - Authorization
      summary: Pure Storage Log in a User
      description: 'Logs in a user and returns a session token, using either the user''s API token or their username and password. `api-token` is passed in a header, with the request body empty. Otherwise `username` and `password` are passed in the request body, without an `api-token` header.

        Storing user passwords client-side is not recommended. The username-password authentication option should only be used as necessary for initial retrieval of an API token, which should be securely stored and used for all subsequent logins.

        '
      parameters:
      - name: api-token
        in: header
        description: 'API token for a user.

          '
        schema:
          type: string
        example: 0f2e2884-9486-c6c2-438c-f50418f2aac3
      - $ref: '#/components/parameters/XRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginPost_2'
        required: false
        x-codegen-request-body-name: login
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              description: Supplied by client during request or generated by server.
              schema:
                type: string
            x-auth-token:
              description: Session token for a user.
              schema:
                type: string
                example: 3be3d489-55c6-4643-90ac-a476dbc98812
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Login'
      x-codegen-request-body-name: login
  /api/logout:
    post:
      tags:
      - Authorization
      summary: Pure Storage POST Logout
      description: 'Invalidate a REST session token.

        '
      parameters:
      - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              description: Supplied by client during request or generated by server.
              schema:
                type: string
          content: {}
  /api/login-banner:
    get:
      tags:
      - Authorization
      summary: Pure Storage GET Login_banner
      description: 'Get the login banner for the array. No authentication is required to access this endpoint.

        '
      parameters:
      - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: OK
          headers:
            X-Request-ID:
              description: Supplied by client during request or generated by server.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginBannerGetResponse'
      security: []
components:
  schemas:
    Login:
      allOf:
      - $ref: '#/components/schemas/Username'
      x-aliases:
      - LoginResponse
    OauthSubjectTokenType:
      type: string
      description: 'An identifier that indicates the type of security token specifed in the `subject_token` parameter.

        The Pure Storage REST API supports the JSON Web Token (JWT)

        as the means for requesting the access token.

        Set `subject_token_type` to `urn:ietf:params:oauth:token-type:jwt`.

        '
      default: urn:ietf:params:oauth:token-type:jwt
    UsernameResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Username'
    LoginBannerGetResponse:
      type: object
      properties:
        login_banner:
          description: The string to show as login banner.
          type: string
          example: Restricted area. Authorized personnel only.
    LoginPost:
      type: object
      properties:
        password:
          description: 'The user password that is used as an alternative to an api-token.

            '
          type: string
        username:
          description: 'The username used to log in as an alternative to an api-token.

            '
          type: string
    _api_versions:
      description: A list of supported API versions.
      type: array
      items:
        type: string
      example:
      - '1.0'
      - '1.1'
      - '1.2'
      - '1.3'
      - '1.4'
      - '1.5'
      - '1.6'
      - '1.7'
      - '1.8'
      - '1.9'
      - '1.10'
      - '1.11'
      - '1.12'
      - '1.13'
      - '1.14'
      - '1.15'
      - '1.16'
      - '1.17'
      - '2.0'
    Username:
      type: object
      properties:
        username:
          description: The username of the user.
          type: string
          example: pureuser
    LoginPost_2:
      type: object
      properties:
        password:
          description: 'User password. Used as an alternative to api-token.

            '
          type: string
        username:
          description: 'User to log in. Used as an alternative to api-token.

            '
          type: string
    Api_versionResponse:
      type: object
      properties:
        version:
          $ref: '#/components/schemas/_api_versions'
    OauthSubjectToken:
      type: string
      description: 'An encoded security ID Token representing the identity of the party on behalf of

        whom the request is being made. The token must be issued by a trusted

        identity provider which must be either a registered application in Pure1

        or an enabled API client on the array. The token must be a JSON Web Token

        and must contain the following claims:


        > | JWT claim | Location | API Client Field | Description | Required By |


        > |-|-|-|-|-|


        > | kid | Header | key_id | Key ID of the API client that issues the identity token. | FlashArray

        and FlashBlade only. |


        > | aud | Payload | id | Client ID of the API client that issues the identity token. | FlashArray

        and FlashBlade only. |


        > | sub | Payload | | Login name of the array user for whom the token should be issued.

        This must be a valid user in the system. | FlashArray and FlashBlade only. |


        > | iss | Payload | issuer | Application ID for the Pure1 or API client''s trusted identity

        issuer on the array. | All products. |


        > | iat | Payload | | Timestamp of when the identity token was issued.

        Measured in milliseconds since the UNIX epoch. | All products. |


        > | exp | Payload | | Timestamp of when the identity token will expire.

        Measured in milliseconds since the UNIX epoch. | All products. |



        Each token must also be signed with the private key that is paired with the

        API client''s public key.


        '
    OauthGrantType:
      type: string
      description: 'The method by which the access token will be obtained.

        The Pure Storage REST API supports the OAuth 2.0 "token exchange" grant type,

        which indicates that a token exchange is being performed.

        Set `grant_type` to `urn:ietf:params:oauth:grant-type:token-exchange`.

        '
      default: urn:ietf:params:oauth:grant-type:token-exchange
  responses:
    OauthToken400:
      description: BAD REQUEST
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: invalid_request
              error_description:
                type: string
                example: 'Unsupported subject_token_type: urn:ietf:params:oauth:token-'
    OauthToken401:
      description: UNAUTHORIZED
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: invalid_client
              error_description:
                type: string
                example: 'Invalid identity: JWT validation failed.'
    OauthToken200:
      description: OK
      content:
        application/json:
          schema:
            title: oauth_token_response
            type: object
            properties:
              access_token:
                description: 'The serialized OAuth 2.0 Bearer token used to perform authenticated requests.

                  The access token must be added to the Authorization header of all API calls.

                  '
                type: string
                example: eyJraWQiOiJqTlBzL1Ria2c4U2Vua3F3ZmkvbnI4bWxxQ3NPIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhdWQiOiI5NDcyMTkwOC1mNzkyLTcxMmUtYTYzOS0wODM5ZmE4MzA5MjIiLCJzdWIiOiJqb2UiLCJyb2xlIjoic3RvcmFnZV9hZG1pbiIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6OTAwMCIsImlhdCI6MTU0NDAzNjA1MiwiZXhwIjoxNTQ0MDcyMDUyLCJqdGkiOiJjOTg0MjgyNS1mNGM3LTRiNGUtODdkNy03OWFiZmIxYTUzNDgifQ.pnuYAx0CkmkIG0LDrMAQGRr5Ci4-t5yMto3A7BkmyKnAVHBXG5ZIWwvNkWDLhqbA4YjmG7LZmWHrCVehLy2zy2vRLahFURsd3GTnOaWSyWFIyrwpoO81jQRtOQATtseweuMT_-C8o3oa4MgBNBsuKrhwKQS3oDDpeRPaCRTGev1_xRDxh_K6CWJBTAeOP2pcR4LW6zIJkCLzzkMuyL4aTJWWUjSbl04mcFbyw8r8W1GURrmaDVOvvpT634Hk9-GGh9OMIRlS6OOq7cJKc-RRWn18IK2Gs53V_KYshXTBbnRr990Y_qOX8MaTWOJTqgzsojY02MSVuJ9XDJWoIU3TQytr4K1vM2EvwDZDgl7LuUYUn7vWhbKktFzpeZyyhOjq3eX-ViugYKpIjBcG2f_-fcTPceEWGV82rd6TyVNB5A-v9u2kxCdW198t_kesgVQfuupDeS02cZe0ABLCzEHPiVF17JfiVr6sjkciioxN7Wj_j18ga4U0mdSukauT8yhbgCW1ijTVTFu1VwWebW0s8z3BWMtXdTtZ3BhcZVAdKRF8bOq7nfEbUQGhTn9g7dK-yF050winjtp-VTL2oUtkF5j1v_N8vPNiN9ZdkGJZr7VVZ-qeOJZcjdaRbxL6YB__yT1wkTcKPh8RHz6GUq7Jbyw8VIlcBE2nvJ63d0tH9C4
              expires_in:
                description: 'The duration after which the access token will expire.

                  Measured in seconds. This differs from other duration

                  fields that are expressed in milliseconds.

                  '
                type: integer
                format: uint32
                example: 35999
              issued_token_type:
                description: 'The type of token that is issued.

                  The Pure Storage REST API supports OAuth 2.0 access tokens.

                  '
                type: string
                example: urn:ietf:params:oauth:token-type:access_token
              token_type:
                description: 'Indicates how the API client can use the access token issued.

                  The Pure Storage REST API supports the `Bearer` token.

                  '
                type: string
                example: Bearer
  parameters:
    XRequestId:
      name: X-Request-ID
      in: header
      description: 'Supplied by client during request or generated by server.

        '
      schema:
        type: string