# 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.

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](/platforms/reference/authentication/). Calling the API with an OAuth access token from account sharing? See [Calling the API with an access token](/platforms/account-sharing/access-tokens/).

## 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:

```bash
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:

```javascript
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:

```bash
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](/merchants/reference/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.