> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.superpath.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Learn how to authenticate with the SuperPath API


# Learn how to authenticate with the SuperPath API

**In this article:**
* Overview
* Getting an API key
* Authenticating a request
* What an API key can access
* Authentication responses
* Managing keys through the API
* Things to keep in mind
* FAQs

## Overview
The SuperPath API authenticates with an API key, sent as a bearer token on every request. There are no OAuth flows, app registrations or client secrets to manage — one key is all you need.

API keys are a **paid-plan** feature and are generated inside SuperPath by an **Owner** or an **Admin**, under **Settings → Integrations**. If you're on a free plan, the **API keys** section points you to your **Billing settings** to upgrade.

## Getting an API key
Generate the key in the app under **Settings → Integrations → API keys**. The step-by-step walkthrough lives in the help article *How to Generate an API Key*.

The key is displayed **once**, at the moment it's created. SuperPath stores only a hashed copy, so it can't be shown to you again or emailed to you later — copy it and store it securely. If you lose it, generate a new key and revoke the old one.

## Authenticating a request
Send the key in the `Authorization` header, prefixed with `Bearer` and a single space:

```http
Authorization: Bearer <your-api-key>
```

![](https://storage.crisp.chat/users/helpdesk/website/c0645e580ffc0800/image_10ua22a.png)

A complete request against the base path `https://api.superpath.io`:

```bash
curl https://api.superpath.io/users \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The same request in JavaScript:

```js
const response = await fetch('https://api.superpath.io/users', {
  headers: {
    Authorization: `Bearer ${process.env.SUPERPATH_API_KEY}`,
  },
});
```

> **Note:** The `Bearer` prefix is required and is matched case-sensitively — `bearer <key>` or the bare key on its own is rejected as a bad request rather than an authentication failure.

You don't need to send any account or tenant identifier alongside the key. The key resolves to the SuperPath user it was generated for, and that user determines which account the request runs against.

## What an API key can access
An API key is not scoped to individual endpoints or resources. Instead, it inherits the role permissions of the SuperPath user it was generated for:

| Aspect | Behaviour |
|---|---|
| Account | Fixed — the account of the user the key belongs to. |
| Permissions | The same permissions that user's role has in the app. A request that the user couldn't make in the UI is refused for the key too. |
| Endpoint scope | None. Any endpoint the user's role permits is reachable with the key. |
| Expiry | None. A key stays valid until it's revoked. |

Because of this, generate keys against a user whose role has exactly the access your integration needs — no more.

## Authentication responses
| Status | What it means |
|---|---|
| `200` / `201` / `204` | The request was authenticated and processed. |
| `400` | An `Authorization` header was sent but didn't contain the `Bearer` prefix. |
| `401` | No credentials were sent, the key isn't recognised, or the key has been revoked. A `401` is also returned when the key is valid but the user's role isn't allowed to perform that action, so treat it as "not authenticated **or** not permitted". |
| `423` | The account is temporarily locked while it's being migrated between regions. Retry later. |

For the full set of status codes the API returns and how to recover from them, see [Learn how to handle and recover from errors received from the SuperPath API](https://help.superpath.io/en/article/learn-how-to-handle-and-recover-from-errors-received-from-the-superpath-api-grdos3/).

## Managing keys through the API
Keys are normally created and revoked in the app, but the same operations are available on the API for an authenticated caller whose role can manage keys:

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/security/apikeys` | List the keys on your account. Only the hashed key is stored, so this never returns a usable key. |
| `POST` | `/security/apikeys` | Create a key. The new key is returned in the response body — this is the only time it's visible. |
| `PUT` | `/security/apikeys/{apiKeyId}/revoke` | Revoke a key. Once revoked, requests using it get a `401`. |

See the [API Reference documentation](https://superpath.readme.io/reference) for the request bodies.

## Things to keep in mind
* Keep your key safe. Anyone who gets access to it can act on your account with the permissions of the user it belongs to.
* Keys are write-once: after a key is created it can't be viewed again, so don't lose it.
* Keep keys server-side. Never put one in client-side JavaScript, a mobile app bundle, or a public repository.
* Use one key per integration, with a descriptive name, so you can revoke a single integration without breaking the others.
* Revoking a key takes effect on the API side, not in your code — anything still using that key will start failing with `401`, so roll the new key out first.
* If a key may have been exposed, revoke it and generate a replacement. See the help article *How to Revoke an API Key*.

## FAQs
**Who can generate API keys?**
Only Account **Owners** and **Admins**. Settings pages aren't available to other roles, and the underlying permission to manage API keys is granted only to those two roles.

**Do API keys expire?**
No. A key remains valid until someone revokes it.

**Can I restrict a key to certain endpoints or to read-only access?**
Not directly — a key carries the permissions of the user it was generated for. To limit what an integration can do, generate its key against a user whose role already has that narrower access.

**I lost my key. Can support retrieve it?**
No. SuperPath only stores a hashed copy, so nobody can recover the original. Generate a new key and revoke the old one.

**I'm getting a 401 and I'm sure the key is right. What else could it be?**
Check that the key hasn't been revoked in **Settings → Integrations**, that the header is `Authorization: Bearer <key>` with the `Bearer` prefix and a single space, and that you're calling `https://api.superpath.io`.

### Feedback
We'd love to hear your feedback and bug reports. Please email us at [support@superpath.io](mailto:support@superpath.io) and share your feedback and comments.