Authentication

Creating an API Key

Navigate to API Keys Settings

1. Log in to your ShipOS dashboard (opens the Cybership dashboard in a new tab)
2. Navigate to your team's settings by clicking on the team name in the navigation
3. Go to ShipOS → Settings → API Keys (opens the Cybership dashboard in a new tab)

Create a New API Key

1. Click the Create API Key button in the top right corner

2. Fill out the creation form:

   • API Key Name: Give your key a descriptive name (e.g., "Production Integration", "Warehouse Scanner App")
   • Description (optional): Add details about what this key will be used for
   • Permission Level: Select the access level for this key:
     • Member: Basic read/write access to fulfillment operations
     • Admin: Full access to all team resources and settings
     • Owner: Complete team ownership access with administrative privileges

3. Click Create API Key

Save Your API Key

After creating the key, you'll see a dialog displaying your new API key:

• The key will start with cyb_
• Click the copy button to copy it to your clipboard
• Store the key securely
• Click Done when you've saved the key

API Key Format

ShipOS API keys start with cyb_ followed by a long string of characters.

Example:

cyb_a1b2c3d4e5f6789012345678901234567890123456789012345678901234_12ab34cd

Using Your API Key

Authentication Header

Include your API key in the X-Access-Token header with every request:

curl -X GET https://api.cybership.io/v1/shipos/orders \
  -H "X-Access-Token: cyb_your_secret_key_here_checksum"

Example Requests

JavaScript/TypeScript

const response = await fetch('https://api.cybership.io/v1/shipos/orders', {
  headers: {
    'X-Access-Token': 'cyb_your_secret_key_here_checksum',
    'Content-Type': 'application/json'
  }
});

Python

import requests

headers = {
    'X-Access-Token': 'cyb_your_secret_key_here_checksum',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.cybership.io/v1/shipos/orders',
    headers=headers
)

Node.js with Axios

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.cybership.io/v1',
  headers: {
    'X-Access-Token': 'cyb_your_secret_key_here_checksum',
    'Content-Type': 'application/json'
  }
});

const orders = await client.get('/shipos/orders');

Managing API Keys

Viewing Existing Keys

On the API Keys settings page (opens the Cybership dashboard in a new tab), you can see:

• Name: The descriptive name you provided
• Description: Any additional details about the key's purpose
• Created At: When the key was created
• Expires At: If the key has an expiration date (or "No Expiration")
• Created By: The user who created the key

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response:

Missing Header

{
  "type": "urn:cybership:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "x-access-token header is missing (Reference this ID for support: 2b4f8a9e7c6d1539)"
}

Invalid Format

{
  "type": "urn:cybership:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The provided x-access-token API key is malformed. Expected format: cyb_<secret>_<checksum> (Reference this ID for support: 9c1e5a3b8f2d7460)"
}

Invalid or Expired Key

{
  "type": "urn:cybership:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key (Reference this ID for support: 4d7b2f1a9e5c8372)"
}

API Key Permissions

API keys inherit permissions based on their access level:

Troubleshooting

Common Issues

1. "x-access-token header is missing"

   • Ensure you're setting the header name correctly (case-sensitive)
   • Check that your HTTP client isn't stripping headers

2. "API key is malformed"

   • Ensure you copied the complete key

3. "Invalid API key"

   • The key may have been deleted or doesn't exist
   • Check you're using the correct key for the environment

4. Rate limit errors after authentication

   • See the Rate Limits guide
   • Consider upgrading your rate limit tier

Testing Authentication

Test your API key with a simple request:

curl -X GET https://api.cybership.io/v1/shipos/orders \
  -H "X-Access-Token: your_api_key_here" \
  -H "Content-Type: application/json" \
  -w "\nHTTP Status: %{http_code}\n"

A successful response will return HTTP status 200 with order data.

Error Trace IDs for Support

When API errors occur, each error response includes a unique trace ID in the detail field to help with troubleshooting:

{
  "type": "urn:cybership:error:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The provided order_id 'not-a-uuid' is invalid. Expected a valid UUID (Reference this ID for support: 1234567890abcdef)"
}

Using Trace IDs for Support

When contacting support about API errors:

1. Include the trace ID: Copy the trace ID from the error message (e.g., 1234567890abcdef)
2. Provide context: Include the endpoint you were calling and the request you made
3. Fast resolution: The trace ID allows our support team to quickly locate the exact error in our logs