openapi: 3.1.0
info:
  title: Authentication
  version: '1.0'
  description: |
    
    ### Authenticating for Documentation
    
    Use the appropriate key(s) for the actions you wish to take on the documentation site. Once you have authenticated, copy the Bearer token contained within the response. Use this bearer token on your first request on any page within the endpoint documentation. Once you have entered your bearer token on one page, that token will be long lived across all other endpoints. Tokens expire after a period of one hour. You may navigate back to the authentication endpoint at any time to change credential types. Doing so will require the use of the new Bearer token generated when switching credentials.  

    ```json
    Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH
    ```
    
    ### Authentication for APIs
    
    All requests to the API need to be accompanied by an authorization header with an authentication token:

    ```json
    Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH
    ```

    Authentication token gives permissions for the client to access their data, and is used to authenticate a request to the API endpoint.

    :::note
    Read our [Quick Start guide](/guides/Getting-Started/your-first-api-request) on how to make your first API request.
    :::

    Authentication tokens are generated via the `authentication` endpoint and expire within 1 hour. They need to be then regenerated. If you’re using our [JavaScript SDK](https://github.com/moltin/js-sdk), this is automatically handled for you.

    There are two main token types available for use within your store `client_credentials` and `implicit`. The [implicit token](/docs/authentication/Tokens/implicit-token) is the more limited of the two, restricting access to mostly read-only, whereas [client credential token](/docs/authentication/Tokens/client-credential-token) has full read and write access.

    For more details on token formatting, see [Content Type](/guides/Getting-Started/content-type).

    :::caution
    Do not use or disclose your `client_secret` in public.
    :::

    ## Client Credentials vs. Implicit Use Case Scenarios

    Typically, you would use the implicit authentication method for client-side browser based applications (i.e. frontend), and client credentials for all administrative tasks (`CRUD`) you need to perform at the backend.

    ## Account Authentication
    
    You can also generate [account tokens](/docs/api/accounts/post-v-2-account-members-tokens) to authenticate account members (shoppers) with one of many available authentication methods. You must use account management authentication token with the implicit token to access orders or account APIs. Using the tokens, you can create and filter orders and addresses.
    
    ## Customer Authentication

    You can also generate [customer tokens](/docs/customer-management/customer-management-api/customer-tokens#post-generate-a-token) to authenticate the customers with single sign-on, or email address and password. You must use customer token with the implicit token to access orders or customer APIs. Using the tokens, you can create and filter orders and addresses.

  contact:
    name: Elastic Path
    url: 'https://www.elasticpath.com'
    email: support@elasticpath.com
  license:
    url: 'https://elasticpath.dev'
    name: MIT
servers:
  - url: 'https://euwest.api.elasticpath.com'
    description: EU West
  - url: 'https://useast.api.elasticpath.com'
    description: US East
security: []
paths:
  /oauth/access_token:
    post:
      summary: Create an Access Token
      tags:
        - Generate an Access Token
      description: |

        ### Client Credentials

        A `client_credentials` token is used when the credentials are not publicly exposed, usually a server-side language such as PHP or Node.js. This type of authentication enables `CRUD` access to all resources.

        `client_id` and `client_secret` are created and managed via [Application Keys](/docs/api/application-keys/create-key).

        To see the access granted by a `client_credentials` token, refer to [Permissions](/docs/authentication/Tokens/permissions).


        ### Implicit

        An `implicit` token is typically used for situations where you are requesting data on the client side and you are exposing your public key. When authenticated implicitly, you can only fetch (`GET`) data with live status (products, categories, brands, etc).

        The `implicit` token is most appropriate for use inside client-side applications, such as JavaScript.

        :::caution
        An `implicit` token can be thought of as a **Read only** token.
        :::
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/Bearer"
              examples:
                client_credentials:
                  summary: Client Credentials
                  # language=JSON
                  value: |-
                    {
                      "data": {
                        "access_token": "xa3521ca621113e44eeed9232fa3e54571cb08bc",
                        "token_type": "Bearer",
                        "expires_in": 3600,
                        "expires": 1524486008,
                        "identifier": "client_credentials"
                      }
                    }
                implicit:
                  summary: Implicit
                  # language=JSON
                  value: |-
                    {
                      "data": {
                        "access_token": "xa3521ca621113e44eeed9232fa3e54571cb08bc",
                        "token_type": "Bearer",
                        "expires_in": 3600,
                        "expires": 1524486008,
                        "identifier": "implicit"
                      }
                    }
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        default:
          $ref: '#/components/responses/InternalServerError'
      operationId: post-oauth-access_token
      requestBody:
        description: ''
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              $ref: '#/components/schemas/Token'
            examples:
              client-credentials:
                summary: Client Credentials
                value:
                  grant_type: 'client_credentials'
                  client_id: 'jJBrLb0q1Q7bZ5GiGttD5T1471b0IeXAVgNyOlw19q'
                  client_secret: 'mzr6gnvdQODSgT3mSxxWIv3y8pAp8cUzDELXa3g4fB'
components:
  schemas:
    Token:
      properties:
        grant_type:
          type: string
          description: 'The grant type, choices are `client_credentials` or `implicit`'
        client_id:
          type: string
          description: Your `client_id`
        client_secret:
          type: string
          description: Your `client_secret`. Only required for client credentials.
      required:
        - grant_type
        - client_id
    Bearer:
      properties:
        access_token:
          type: string
          description: The access token you use for subsequent authenticated requests to the API.
        token_type:
          type: string
          description: Right now this is only `Bearer`.
        identifier:
          type: string
          description: The type of token requested. This can be a `client_credentials` or `implicit`.
        expires_in:
          type: integer
          description: The duration in seconds after which the token expires.
        expires:
          type: integer
          description: The epoch time that this token expires at.
    Error:
      required:
        - status
        - title
      properties:
        title:
          type: string
          description: A brief summary of the error.
          examples:
            - "Bad Request"
        status:
          type: string
          format: string
          description: The HTTP response code of the error.
          examples:
            - "400"
    ErrorResponse:
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
  responses:
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              summary: Internal server error
              # language=JSON
              value: |
                {
                  "errors": [
                    {
                      "title": "Internal Server Error",
                      "status": "500",
                      "detail": "there was a problem processing your request"
                    }
                  ]
                }
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            bad-request-error:
              # language=JSON
              value: |
                {
                  "errors": [
                    {
                      "title": "Bad Request",
                      "status": "400"
                    }
                  ]
                }
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized-error:
              # language=JSON
              value: |
                {
                  "errors": [
                    {
                      "title": "Unauthorized",
                      "status": "401"
                    }
                  ]
                }