Guides

API Authentication

Suggest Edits

Storefront API Authentication

To interact with Nacelle's GraphQL Storefront API, you may need to provide a valid access token. Note that the API does not demand customer-specific authentication; in other words, there's no need for a customer username or password to access most features.

Authentication vs Authorization

  • Authentication: This is the process of confirming an entity's identity. In the context of the Storefront API, it involves providing a valid access token to confirm that the request is coming from a known source.
  • Authorization: Once authenticated, authorization determines the level of access an entity has. With the Storefront API, your access level is determined by the type of access token you possess: private or public.

Types of Access Tokens

The Storefront API offers two types of access tokens:

  • Private Access Tokens: Suitable for server-side interactions and meant to be kept secure.
  • Public Access Tokens: Designed for client-side operations, like those originating from a web browser or a mobile app.

Private Access Tokens

Private access tokens are designed for making API requests from a secure server environment.

⚠️

Caution: These tokens should never be exposed in client-side code as they are meant to be confidential.

How to Obtain a Private Access Token

If you haven't set up your Nacelle client credentials yet, start by following our Client Credentials Guide.

Here's an example command to obtain a private access token:

curl -X POST https://authimilate.api.nacelle.com/v1/credential/token \
   -H 'content-type: application/json' \
   -d '{"client_id":"CLIENT_ID","client_secret":"CLIENT_SECRET","audience":"noms.api.nacelle.com","grant_type":"client_credentials"}'

Note: Replace "CLIENT_ID" and "CLIENT_SECRET" with your specific credentials.

Parameters Explained:

  • CLIENT_ID: This is the unique identifier for your client application within the Nacelle ecosystem. The CLIENT_ID helps Nacelle recognize which application is sending the request. You'll receive this ID when you initially set up your client credentials in Nacelle.
  • CLIENT_SECRET: This is the confidential key associated with your CLIENT_ID. It serves as a password for your application, ensuring that only authorized users can gain access to secured Nacelle data. Like the CLIENT_ID, you'll obtain this secret during the client credential setup process.

Remember to treat these parameters, especially the CLIENT_SECRET, as sensitive information. Never expose them in client-side code or public repositories.

To utilize this token, include it in the Authorization header for all your server-side API requests.

Public Access Tokens

Public access tokens are used for client-side interactions and are generally scoped to a particular customer or user segment.

How to Obtain a Public Access Token

To get a public access token, you must first have a valid private access token.

curl -X POST "https://authimilate.api.nacelle.com/v1/issue" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer PRIVATE_ACCESS_TOKEN" \
   -H "X-Nacelle-Space-ID: SPACE_ID" \
   -d '{"customer_id":"CUSTOMER_ID","segment_id":"SEGMENT_ID"}'

ⓘ NOTE: Replace "YOUR_PRIVATE_ACCESS_TOKEN", "YOUR_SPACE_ID", "YOUR_CUSTOMER_ID", and "YOUR_SEGMENT_ID" with the appropriate values.

Parameters Explained:

  • PRIVATE_ACCESS_TOKEN: This is the private access token that you obtain using your Nacelle client credentials. This token grants your server the necessary permissions to issue public access tokens and should be securely stored.
  • SPACE_ID: This is the identifier for your specific "space" or project within Nacelle. It helps Nacelle route your request to the appropriate data and configuration settings.
  • CUSTOMER_ID: This is the unique identifier for the customer for whom you are issuing the public access token. This ID is usually specific to your business logic or database.
  • SEGMENT_ID: This is the identifier for a particular customer segment, allowing you to customize the experience based on different customer groups or market segments. This ID is also specific to your business logic.

When making API requests from the client-side, include the public access token in the Authorization header.

Updated 6 months ago