Skip to main content

Overview

The Shipstar API uses Bearer token authentication. There are two types of tokens depending on which API you’re using:

API Key Authentication

API keys are used for programmatic access to the Shipstar API. Include your key in the Authorization header:

Creating API Keys

1

Sign In

Go to app.shipstar.ai and sign in to your account.
2

Navigate to API Keys

Click on API Keys in the sidebar.
3

Create New Key

Click Create API Key and enter a descriptive name.
Use descriptive names like “Production Server”, “Development”, or “CI/CD Pipeline” to easily identify keys later.
4

Copy and Store Securely

Copy your API key immediately and store it securely. You won’t be able to view the full key again — only a short prefix (shp_ and the next eight characters) is kept for identification. Every Shipstar key starts with shp_, so secret scanners can recognise one that leaks.
Never share your API key or commit it to version control.

Rotating a key

Rotate a key instead of deleting and recreating it when you want a fresh secret without losing the key’s name and request history. From the API Tokens page, choose Rotate on the key and pick a grace window: The new key is shown once, like a freshly created one. Until the window closes, both the old and the new secret authenticate, so you can update callers one at a time. Rotating again inside the window replaces the previous secret: at most two secrets are ever live for one key. The page shows the previous key’s prefix and its deadline while it is still valid.

API Key Details

  • Keys are hashed with SHA-256 before storage — Shipstar never stores your raw key
  • Each key tracks a last_used_at timestamp
  • Keys can have an optional expiration date
  • Keys can be deactivated without deletion

JWT Session Authentication

The internal API (dashboard endpoints) uses JWT tokens obtained by logging in:
Response
Use the JWT token the same way as an API key:

Token Refresh

JWT tokens expire after a configurable period. Refresh an expired token (within a 30-day grace period) at:

Implementation Examples

Environment Variables

Always store your API key in environment variables:

Backend Proxy Pattern

For web applications, create a backend proxy to keep your API key secure:

Reusable Client

Create a reusable client for your application:

Security Best Practices

API keys should never be included in frontend JavaScript, mobile apps, or anywhere they can be viewed by end users.
Store API keys in environment variables, never in code:
  • Use .env files for local development
  • Use secret management services in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Never commit .env files to version control
Establish a key rotation schedule:
  1. Create a new API key
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. Deactivate the old key
Create different API keys for development, staging, and production. This limits the impact if a key is compromised and makes auditing easier.
Regularly review your API usage in the Dashboard to detect unusual activity patterns and identify compromised keys.

Troubleshooting

Possible causes:
  • API key is missing from the request
  • API key has been deactivated or expired
  • Using a JWT token that has expired (refresh it)
Solutions:
  • Verify the Authorization header is present with the Bearer prefix
  • Check that the key hasn’t been deactivated in the Dashboard
  • Create a new API key if needed
Possible causes:
  • Accessing a resource that belongs to another project or team
  • Account restrictions
Solutions:
  • Check that your API key belongs to the correct project
  • Verify your account permissions in the Dashboard

Testing Your API Key

Use this request to verify your API key is working:
A successful response confirms your key is valid: