Fix authentication errors with your API key

A 401 Unauthorized response means Shipstar could not verify your identity from the credentials you sent. This is almost always caused by one of a small number of issues with how the API key is formatted or the state of the key itself, and each has a straightforward fix.

Common causes and fixes

1. Missing Bearer prefix. The Authorization header must read Bearer YOUR_API_KEY — the word Bearer followed by a space, then the key. Sending the key alone, or using a different header name such as Api-Key, will always return a 401.
2. Deactivated or expired key. Keys can be deactivated without being deleted, and they can be given an optional expiration date. If your key was working before and has suddenly stopped, check the API Keys page in the dashboard to confirm the key is still active and has not passed its expiry.
3. Mistaking a JWT session token for an API key. Shipstar uses two different types of Bearer token: API keys (created in the dashboard under API Keys) for programmatic access, and short-lived JWT tokens for the internal dashboard API. If you obtained a token by calling the login endpoint and are using it against a public API endpoint — or vice versa — you will receive a 401. Use an API key for the GET /api/v1/me endpoint and any other v1 authenticated endpoint.
4. Typo in the key. Only the first 8 characters of each key are displayed in the dashboard after creation, so you cannot retrieve the full key again. If you suspect a transcription error, create a new key.

How to create a new API key

1. Sign in at app.shipstar.ai.
2. Click API Keys in the sidebar.
3. Click Create API Key, give it a descriptive name, and copy it immediately — you will not be able to view the full key again after leaving the page.
4. Store the key in an environment variable or secrets manager, never in source code.

Tips

• Use a descriptive key name (for example, Production, CI/CD Pipeline) so you can identify and rotate keys easily.
• If you need to retire a key, deactivate it in the dashboard rather than deleting it — deactivated keys stop working immediately while keeping the record for audit purposes.
• JWT tokens expire after a set period. If you are using the internal API and receive a 401 after a session has been running for a while, refresh the token via /api/internal/auth/jwt/refresh.