​
Overview

fabric authenticates and authorizes API requests using your account’s API keys. Before invoking any fabric API, API clients are required to have an API key that must be included as part of the requests. These keys are used to validate the permissions and access rights associated with the client before allowing access to a specific merchant’s data.

Only users with Admin or Restricted Admin roles can create, view, edit, or delete API apps and associated keys. Users with other roles will have to reach out to an Admin or Restricted Admin to get details regarding specific API apps.

​
Types of fabric API Apps

There are two types of API Apps in Copilot:

  • User App: This type of app uses fabric Identity to authenticate end users. A User App relies on the login page that fabric Identity hosts in order for end users to log in. It is suitable for e-commerce apps that direct their authentication and authorization needs to fabric Identity.
  • System App: This type of app generates an access token to identify itself using a client ID and client secret. System Apps do not use fabric Identity to authenticate end users; rather they use system-to-system communications with fabric APIs. If you are using your own identity provider, you should create a System App.

Visit the Concepts page to learn more about User Apps and System Apps.

​
Terminology

The following terminology is used when creating or managing fabric API Apps:

  • App Name: Name of the app
  • App Type: The app type, whether User or System. Choose “User App“ if you are using fabric Identity with your storefront. Choose “System App“ if you want to integrate with fabric APIs while using your own identity provider.
  • Role: Scope of permissions for the app
  • User Pool: The user directory where user credentials are stored
  • Redirect URL: The URL the user should be redirected to after successful authentication.
  • Logout URL: The URL the user should be redirected to after logout
  • Authorization URL: URL to which the user will provide their client id and client secret to. If authorization is successful, then the user will be redirected to their redirect URL with an access token.
  • Client Id: Public identifier for an app
  • Client Secret: Secret known only to your application and the authorization server used to authenticate the app.

​
Creating and Managing API Apps

To view, create, edit, and delete apps, visit the API Apps page by logging in to Copilot, clicking on Developer Tools in the panel at the left, and selecting API Apps.

​
Creating API Apps

Click the Add API App button to create a new API app. Fill out the App Name and Description and use the App Type dropdown menu to select between System App and User App.

If System App is selected, choose a Role for the app. The role sets the scope of permissions for the app by restricting what it can do. System capabilities are mapped to user permission levels (e.g.: admin, editor, and viewer).

The following are the available roles and their capabilities:

  • Admin: has admin role access for all fabric products
  • Editor: has editor role access for all fabric products
  • Viewer: has viewer role access for all fabric products
  • Offers Editor: can create, update, and delete prices, promotions, customer segments, and exclusions in Offers
  • Orders Editor: can manage orders, locations, inventory, networks, and settings in Orders
  • Product Catalog Editor: can create, update, and send for review catalog changes in Product Catalog
  • Experiences Editor: can create content for usage on storefronts in Experiences
  • Experiences Publisher: can review content and approve for publishing in Experiences

If User App is selected, fill out the following fields:

  • User Pool: The user directory where user credentials are stored.
  • Redirect URL: The URL the user is directed to after successful authentication.
  • Logout URL: The URL the user is directed to after logout.

After filling out the fields under App information, click Create to create the application.

  • If creating a User App, follow the steps under the section Working with User Apps to integrate your storefront with fabric Identity
  • If creating a System App, follow the steps in the section Working with System Apps to generate access tokens and start accessing fabric APIs

​
Viewing API Apps

The API Apps page has a list of all the API apps you’ve created previously. Click on an App to view its details.

The Auth Settings section provides the authentication information associated with the app (e.g., authorization URL, Client ID, Client Secret). This information is needed to access the APIs.

API endpoints for some of fabric’s products, like Cart and Checkout and Product Catalog, require X-API-KEYs. You will see this information in the Auth Settings section based on the products you use.

​
Editing API Apps

The API Apps page has a list of all the API apps you’ve created previously. To edit an app, click on its corresponding pencil icon.

The App Name and Description can be edited for a System App; the App Name, Redirect URL, Logout URL, and Description can be edited for a User App.

Click Save when finished.

​
Deleting API Apps

To delete an app, click on the corresponding trashcan icon and click Yes, Delete to delete the app.

​
Working with User Apps

In order to start integrating fabric Identity with your storefront follow the steps below.

  • Clone the following Okta GitHub repository and follow the steps in readme for setting up the hosted login page from local machine.
  • Follow the steps mentioned in readme and update the configurations with the Issuer (Authorization Server URL) and clientId of the user app created in previous step.
  • Start the app in root folder with npm run okta-hosted-login-server.

The hosted app starts in 8080 port of local machine and as follows:

As the user enters the credentials and proceeds with log in, the user would be able to login to the sample app hosted in local machine and get the token from developer tools>application tab>local storage>okta-token-storage.

To learn more about working with User Apps, visit the User Apps section of the Developer Portal.

​
Working with System Apps

In order to start accessing fabric APIs, generate an access token by taking the following the steps:

  • Get an access token by calling the /token endpoint.

curl --location --request POST '{{authURL}}/v1/token' \ --header 'accept: application/json' \ --header 'cache-control: no-cache' \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=s2s' \ --data-urlencode 'client_id={{clientId}}' \ --data-urlencode 'client_secret={{clientSecret}}'

  • Replace clientId , clientSecret, and authURL in the above endpoint with the values your app generated.
    Note: authURL is a unique URL for each fabric merchant and is common across all Sysapps defined for a single merchant.
  • The /token endpoint returns the access token in the following response structure:

{ "token_type": "Bearer", "expires_in": 600, "access_token": "eyJraWQiOiIt...", "scope": "s2s" }

Use access_token to begin querying fabric APIs.

The DNS of the sign in/sign out redirect URLs should be whitelisted with fabric (in the above example, http://localhost:8080).

To learn more about working with System Apps, visit the System Apps section of the Developer Portal.

​
Additional notes

Was this page helpful?

Security & ComplianceOverview