Authentication with API keys

If you are integrating your own Shuttle account, you authenticate with your account’s secret key. It reaches only your account.

Building a platform for many merchants? See Authentication for platforms. Calling the API with an OAuth access token from account sharing? See Calling the API with an access token.

Where to find your API key

In the Merchant Portal, open your account, select Configure, then select Configure in the Account section. You need the Admin role. API keys come with the paid plans: on other plans the API Keys section is marked UPGRADE instead.

The API Keys section shows your API endpoint, https://app.shuttleglobal.com/c/api/instances/{instance_key}, and a ready-made Authorization header. Select show to reveal the header.

Keep the key on your server. Anyone with it can take and refund payments on your account, so never put it in a browser, a mobile app or a code repository.

Sending your key

Use HTTP Basic authentication with your secret key as the username and a blank password, and put your instance key in the path:

curl -u "$SHUTTLE_SECRET_KEY:" \
  "https://app.shuttleglobal.com/c/api/instances/$SHUTTLE_INSTANCE_KEY/transactions?limit=1"

Note the colon after the key: it separates the username from the empty password. If you build the header yourself, Base64-encode the key followed by a colon. This gives the same header the Merchant Portal shows, so you can also copy it from there:

const auth = Buffer.from(`${process.env.SHUTTLE_SECRET_KEY}:`).toString('base64')

const response = await fetch(
  `https://app.shuttleglobal.com/c/api/instances/${process.env.SHUTTLE_INSTANCE_KEY}/transactions?limit=1`,
  { headers: { Authorization: `Basic ${auth}` } }
)
const { transactions, meta } = await response.json()

A successful call returns your most recent transaction in a transactions list, and meta gives the limit, offset and total.

Instance key as the username

You can also send your instance key as the username and the secret key as the password. The credentials then say which account the request is for, so leave the instance out of the path:

curl -u "$SHUTTLE_INSTANCE_KEY:$SHUTTLE_SECRET_KEY" \
  "https://app.shuttleglobal.com/c/api/transactions?limit=1"

Using the API reference

Every endpoint in the Merchant Instance API works with your key. The reference shows each path as /c/api/instances/{instance_key}/...: use your own instance key there.

When authentication fails

A request with a missing or invalid key gets a 401 response. Check that you are sending the secret key with a blank password, and that the URL includes your instance key.