Skip to main content

Third Party Tokens

This guide outlines the additional tokens and credentials you may need based on your project's integrations and requirements. While none of these tokens are required unless you plan to integrate with the specified services, having them ready beforehand will streamline your setup process. When running the create scripts, you will be prompted for these tokens based on your selections.

Key Tokens and Credentials​

Design System​

If you plan to create a Design System project and sync theme tokens from Figma, you’ll need:

  • Figma Token: A personal access token to authenticate with the Figma API.
  • Figma ID: The unique identifier for your Figma file.
info

Figma Token: Go to Figma, log in with your Acromedia email, and navigate to Settings > Personal Access Tokens > Generate New Token.

Figma ID: This corresponds to the unique identifier of your Figma file. If you are unsure where to get this, reach out to someone from UX assigned to your project.

Commerce Options​

For projects with a commerce platform, configure the following based on your selected platform.

Drupal Commerce​

  • Commerce URL: Base URL for Drupal Commerce, stored in NEXT_PUBLIC_DRUPAL_URL.

BigCommerce Integration​

  • X-Auth-Token: BigCommerce API access token.
  • Store Hash: A unique identifier for your store.
  • Storefront URL: Your .mybigcommerce.com storefront address.
info

Store Hash: Log in to your BigCommerce store, go to Advanced Settings > API Accounts > Create API Account (V2/V3 Token). You can find a field named API Path, with the following structure: https://api.bigcommerce.com/stores/<storehash>/v3.

X-Auth-Token: Create an OAuth API account to generate access tokens. Pass the access token as the value of the X-Auth-Token header when making authenticated requests.

Shopify Integration​

  • Shopify Store Domain: Your store’s .myshopify.com domain.
  • Shopify Storefront API Token: Used to authenticate with the Shopify Storefront API.
  • Shopify Admin Access Token: For Shopify Admin API access.
info

Storefront API Token:

  1. Log in to your Shopify Admin dashboard.
  2. Go to Settings > Apps and sales channels > Develop apps.
  3. If you already have an app installed and configured, click into it and find the token under API credentials.
  4. Otherwise, create a new app:
    • Click Create an app.
    • Set the Admin and Storefront API scopes as needed.
    • After saving, find your token under API credentials.

ERP Options​

To integrate an ERP system like Acumatica, include the following credentials.

Acumatica Integration​

To integrate Acumatica with your Gesso project, you'll need:

  • acumaticaUrl: The base URL for the Acumatica instance (e.g., https://<your_acumatica_domain>.com).

Authentication (Required if using Acumatica for ERP or Commerce):

  • acumaticaUsername: The username for your Acumatica account.
  • acumaticaPassword: The password for your Acumatica account.
  • acumaticaClientId: The client ID for Acumatica OAuth authentication.
  • acumaticaClientSecret: The client secret for Acumatica OAuth authentication.
info

How to Obtain Acumatica Setup Information:

  1. Log in to your Acumatica instance using your username and password.

  2. Navigate to Settings: Look for the Settings or Administration section in the main menu.

  3. Find API or Integration Settings: Search for options related to APIs, integrations, or developer tools.

  4. Obtain Client ID and Client Secret:

    • If Acumatica offers OAuth authentication, you should find a section where you can create a new OAuth application.
    • Provide the necessary details and generate the client ID and client secret.

  5. Retrieve Base URL:

    • The base URL of your Acumatica instance is typically the URL you use to access the login page, usually in the format https://<your_acumatica_domain>.com.

CMS Options​

For projects including a CMS, the following tokens or information might be required:

  • CMS Preview Secret: Used to securely preview unpublished content within your CMS environment. Configure this using cmsPreviewSecret in the CLI to allow staging previews without publishing.
  • CMS URL: The base URL for the CMS.

Storyblok Integration​

If using Storyblok, gather:

  • Storyblok Access Token: For accessing the Storyblok API.
  • Story Version: Use draft or published to fetch content. For preview mode, set to draft.
info

Storyblok Access Token: Obtainable from your Storyblok account under API credentials. Use draft for previewing unpublished content.

Drupal Integration​

If you already have a Drupal instance, all you will need is the URL. If you do not have one, you can choose to create a Drupal project via the script or continue without Drupal.

GitLab Integration​

If you plan to set up a CMS backend like Drupal using the create script, you'll need:

  • GitLab Token: A personal access token to authenticate with the GitLab API during project setup.

Usage in Create Script​

When running the create script to set up your project, if you choose to set up a CMS backend (e.g., Drupal), the script may require access to private GitLab repositories or packages during the setup process. The gitlabToken is used to authenticate with GitLab to allow the script to access these resources.

Specifically, during the Setup CMS Backend task, the gitlabToken is injected as the TOKEN environment variable during the Composer create-project command. This allows Composer to authenticate with GitLab to fetch any private packages or dependencies required for your CMS backend setup.

If you have not provided the gitlabToken via command-line arguments or environment variables, the create script will prompt you to enter it when necessary.

note

Why is gitlabToken Needed?

  • Access to Private Repositories: If your CMS backend relies on private GitLab repositories or Composer packages, the gitlabToken provides the necessary authentication to access them during setup.
  • Automated Setup: Providing the gitlabToken ensures all dependencies are correctly fetched without manual intervention during the automated setup process.

How to Obtain a GitLab Token​

To generate a GitLab personal access token, follow these steps:

  1. Log in to GitLab: Go to GitLab and log in to your account.
  2. Access Personal Access Tokens:
    • Click on your profile picture in the top-right corner and select Edit profile.
    • In the left sidebar, select Access Tokens.
  3. Create a New Personal Access Token:
    • Name: Enter a name for your token (e.g., "Gesso Project Token").
    • Scopes: Select the necessary scopes for your project. For repository management and CI/CD operations, you might need:
      • api
      • read_user
      • read_repository
      • write_repository
      • read_api
    • Expires at: (Optional) Set an expiration date for the token.
  4. Generate the Token:
    • Click Create personal access token.
    • Important: Copy the generated token immediately and keep it secure. You won't be able to view it again after leaving the page.

Use this token in your project setup when prompted for the gitlabToken.

warning

Security Reminder: Keep your GitLab token secure. Do not commit it to your repository or expose it in any public configurations.