Skip to main content
BunShip provides two authentication mechanisms. Choose the right one based on your use case.

​
JWT Bearer Tokens

Best for: user-facing applications (web apps, mobile apps, SPAs).

​
Getting Tokens

Call the login endpoint with valid credentials: 
curl -X POST https://api.bunship.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd"
  }'
The response includes an access token and a refresh token: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 900
}

​
Using Bearer Tokens

Include the access token in the Authorization header on every authenticated request: 
curl https://api.bunship.com/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

​
Token Lifetimes

TokenLifetime
Access token15 minutes
Refresh token7 days

​
Refreshing Tokens

Before the access token expires, call the refresh endpoint with the refresh token: 
curl -X POST https://api.bunship.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIs..."}'
This returns a new token pair and invalidates the previous refresh token (rotation). Store the new refresh token for the next rotation.

​
Two-Factor Authentication

If the user has 2FA enabled, the login request must include a twoFactorCode: 
curl -X POST https://api.bunship.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd",
    "twoFactorCode": "123456"
  }'
Without the code, the login will fail with a 401 response indicating that 2FA verification is required.

​
API Key Authentication

Best for: server-to-server integrations, CI/CD pipelines, and background jobs.

​
Creating an API Key

API keys are created through the Create API Key endpoint or the dashboard. The full key is only shown once at creation time — store it securely.

​
Using API Keys

Include the key in the X-API-Key header: 
curl https://api.bunship.com/api/v1/organizations/org_abc123/members \
  -H "X-API-Key: bsk_live_abc123..."

​
Key Properties

PropertyDescription
ScopesRestrict which endpoints the key can access
Rate limitPer-key request rate limit (requests/minute)
ExpirationOptional expiration date
OrganizationKeys are scoped to a single organization

​
Key Prefixes

API keys use the prefix bsk_live_ in production and bsk_test_ in test environments. Only the prefix is stored; the full key cannot be retrieved after creation.

​
Which Method to Use

ScenarioMethod
Web or mobile app on behalf of a userJWT Bearer Token
Backend service calling the APIAPI Key
CI/CD pipelineAPI Key
Webhook receiver verificationAPI Key
One-off scriptsAPI Key
Interactive API explorationJWT Bearer Token

​
Security Recommendations

  1. Never expose tokens in URLs — always use headers.
  2. Store refresh tokens securely — use HTTP-only cookies or encrypted storage.
  3. Rotate API keys periodically — revoke old keys and create new ones.
  4. Use scoped API keys — grant only the permissions the integration needs.
  5. Enable 2FA — adds a second layer of protection to user accounts.