docs
  1. Api-guides/admin-api
  2. Getting Started
  3. Authentication & Authorization

Authentication & Authorization

The Admin API uses API keys to authenticate requests. You can generate and maintain your API keys in the SCAYLE Panel by navigating to Settings ➜ General ➜ API Keys.

Authentication to the API is performed via the HTTP Header with your API key as the X-Access-Token value. You do not need to provide a password.

Access your Admin API by calling https://{{tenant-space}}.admin.api.scayle.cloud/api/admin/v1.

If your Tenant is "acme" and the space is "live" the Admin API URL is:

https://acme-live.admin.api.scayle.cloud/api/admin/v1

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

API requests without authentication will also fail.

Your API Tokens grant many privileges, so it is important to use and store them in a secure way. Do not use your token in client-side code or any publicly accessible areas like Git repositories.

Authorization

Each API Key needs to have so-called "resources" assigned. A resource is a group of endpoints; for example, "Products" and "Variants" are combined into a resource called "Products." You can select "read" or "write" permissions when assigning resources. Note that selecting "write" permissions automatically includes read permissions as well. You can assign the resources to API keys in the SCAYLE Panel.

In addition to resources, it's possible to restrict tokens to

  • companies
  • shops*
  • IP ranges

You can either include or exclude certain companies/shops in your list of companies and shops. Including companies or shops means the respective token is eligible to access endpoints tied to these entities only.

On the other hand, excluding a company or a shop means the respective token is not allowed to access any resource tied to that company/shop.

Some endpoints require IP restrictions. To allow only specific IPs, you can define allowed IP ranges in the SCAYLE Panel (CIDR notation).

* You'll define the restrictions at the shop level, not at the shop-country level. That means each shop country inherits the permissions of its parent shop.

If an API key does not have sufficient privileges for the requested endpoint, the API will return a 403 Forbidden error:

In case an API key has been deleted or is expired, you will encounter a 401 Unauthorized error:

Authenticated Request

Depending on your language, initialize your client:

Test Connection

To test your connection, attempt a query to retrieve information about all the shops in your system.

If you have a new instance and no shops with products have been created, the above query would result in an empty response.