Authentication

Types of API keys

There are 2 types of API keys that you can generate:

• Public (aka publishable) keys are prepended by pk_ and are meant to be used in client-side code. For example, for use with our JS, iOS, or Android SDKs.
• Secret keys are prepended by sk_ and are meant to be used in secure environments, such as during server-to-server communication with our API.

The vast majority of API endpoints require authentication through a secret key. Only certain endpoints can be authenticated through a public key. Endpoints that can be authenticated through a public key can also be authenticated through a secret key.

❗️

Be very careful not to expose secret keys in client-side code

If you find that you have accidentally exposed a secret key, immediately rotate and delete the key!

Generating API keys

The first thing we need to do is to generate API keys to access the API. Please log in to Shipped Suite Admin and click on "Administration -> API Keys" on the left hand menu. Click on the "Generate Key" button and then on the next page, give your new API key a name (e.g. "JS publishable key") and select "Public" in the dropdown. Click on "Create".

You have just generated your first public API key. Write this token down and enter it into your application's credentials store.

Repeat the process but change "Public" to "Secret" to generate a secret key.

🚧

Secret keys will only be shown once

Please note that if you create a new API key of type secret, the token will only be displayed once, immediately after creation. Is is not possible to retrieve the token after this, so please take note of it.

Authenticating the API

All API endpoints that require authentication require the API key token to be passed in the Authorization header. For example, using curl:

curl "api_endpoint_here" \
  -H "Authorization: pk_production_a238d34b83d3e68628704c9b91d82bd18bd20a48cfe21bc8f2065f23af897a3f"

Key rotation and security

The following are our recommendations and reminders for managing your API keys:

• Never use a secret key in client-side code (e.g. your website frontend, your mobile apps, etc.)
• Periodically rotate your API keys by creating new ones in your Shipped Suite Admin and swapping them out in your code
• Delete any unused/rotated API keys
• While we allow you to create any number of API keys, we recommend only keeping API keys that are actively in use
• We recommend giving your keys useful names that relate to the codebase that is employing the key