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:

Authorization: Bearer <your-api-key>

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

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

The same request in JavaScript:

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.

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 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 and share your feedback and comments.

Updated on: 25/07/2026

Was this article helpful?

Thank you!