Authentication Guide

Overview

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

API	Token Type	How to Get
Internal API (`/api/internal/`)	JWT session token	Login via `/api/internal/auth/jwt/login`
Public API (`/api/v1/me`)	API key	Create in the Dashboard
Public content (`/api/v1/changelogs`, `/api/v1/blogs`, etc.)	None required	Publicly accessible

API Key Authentication

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

Authorization: Bearer YOUR_API_KEY

Creating API Keys

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

Navigate to API Keys

Click on API Keys in the sidebar.

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.

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 the first 8 characters are stored for identification.

Never share your API key or commit it to version control.

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:

# Login to get a JWT token
curl -X POST "https://app.shipstar.ai/api/internal/auth/jwt/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=your_password"

Response

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer"
}

Use the JWT token the same way as an API key:

Authorization: Bearer eyJhbGciOiJIUzI1...

Token Refresh

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

curl -X POST "https://app.shipstar.ai/api/internal/auth/jwt/refresh" \
  -H "Authorization: Bearer YOUR_EXPIRED_TOKEN"

Implementation Examples

Environment Variables

Always store your API key in environment variables:

SHIPSTAR_API_KEY=your_api_key_here

const API_KEY = process.env.SHIPSTAR_API_KEY;

const response = await fetch('https://app.shipstar.ai/api/v1/me', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

import os
import requests

API_KEY = os.environ.get('SHIPSTAR_API_KEY')

response = requests.get(
    'https://app.shipstar.ai/api/v1/me',
    headers={'Authorization': f'Bearer {API_KEY}'}
)

Backend Proxy Pattern

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

// app/api/generate/route.ts
export async function POST(req) {
  const { contentType, startDate, endDate } = await req.json();

  const response = await fetch(
    `https://app.shipstar.ai/api/internal/sources/github/${contentType}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SHIPSTAR_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ start_date: startDate, end_date: endDate })
    }
  );

  const data = await response.json();
  return Response.json(data, { status: response.status });
}

// Call your backend proxy, not the Shipstar API directly
const response = await fetch('/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ contentType: 'changelog' })
});

Reusable Client

Create a reusable client for your application:

// lib/shipstar-client.ts
class ShipstarClient {
  private apiKey: string;
  private baseUrl = 'https://app.shipstar.ai';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request(endpoint: string, options: RequestInit = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error ${response.status}: ${error.detail}`);
    }

    return response.json();
  }

  async me() {
    return this.request('/api/v1/me');
  }

  async generateChangelog(startDate?: string, endDate?: string) {
    return this.request('/api/internal/sources/github/changelog', {
      method: 'POST',
      body: JSON.stringify({ start_date: startDate, end_date: endDate })
    });
  }

  async getContent(contentId: string) {
    return this.request(`/api/internal/sources/content/${contentId}`);
  }

  async publishContent(contentId: string) {
    return this.request(`/api/internal/content/${contentId}/publish`, {
      method: 'POST'
    });
  }
}

// Usage
const shipstar = new ShipstarClient(process.env.SHIPSTAR_API_KEY!);
const { content_id } = await shipstar.generateChangelog();

Security Best Practices

Never expose keys in client-side code

API keys should never be included in frontend JavaScript, mobile apps, or anywhere they can be viewed by end users.

// ❌ NEVER do this in frontend code
const response = await fetch('https://app.shipstar.ai/api/v1/me', {
  headers: { 'Authorization': 'Bearer sk_abc123' }
});

// ✅ Call your backend instead
const response = await fetch('/api/me');

Use environment variables

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

Rotate keys regularly

Establish a key rotation schedule:

Create a new API key
Update your application to use the new key
Verify the new key works in production
Deactivate the old key

Use separate keys for environments

Create different API keys for development, staging, and production. This limits the impact if a key is compromised and makes auditing easier.

Monitor key usage

Regularly review your API usage in the Dashboard to detect unusual activity patterns and identify compromised keys.

Troubleshooting

401 Unauthorized

{ "detail": "Invalid or expired API token." }

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

403 Forbidden

{ "detail": "Not authorized" }

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:

curl -X GET "https://app.shipstar.ai/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response confirms your key is valid:

{
  "id": "uuid",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "is_active": true,
  "is_verified": true
}

Get Started

Guides

Authentication Guide

Overview

API Key Authentication

Creating API Keys

API Key Details

JWT Session Authentication

Token Refresh

Implementation Examples

Environment Variables

Backend Proxy Pattern

Reusable Client

Security Best Practices

Troubleshooting

Testing Your API Key

​Overview

​API Key Authentication

​Creating API Keys

​API Key Details

​JWT Session Authentication

​Token Refresh

​Implementation Examples

​Environment Variables

​Backend Proxy Pattern

​Reusable Client

​Security Best Practices

​Troubleshooting

​Testing Your API Key

Overview

API Key Authentication

Creating API Keys

API Key Details

JWT Session Authentication

Token Refresh

Implementation Examples

Environment Variables

Backend Proxy Pattern

Reusable Client

Security Best Practices

Troubleshooting

Testing Your API Key