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" } ] }