API referenceGetting started

Authentication

Send your API token as a Bearer token in the Authorization header.

1 min read

API tokens

The Mothership API uses tokens to authenticate requests. Organization owners create tokens on the API settings page in the dashboard. Sandbox and production tokens are separate, and each environment can have two active tokens at a time, so you can switch to a new token before you revoke the old one.

If the API page isn't in your dashboard settings, your organization doesn't have API access yet. Reach out to developers@mothership.com, and a member of our developer relations team will be in touch to set up access and help with onboarding.

Authorization header

To authenticate a request, include your API token as a Bearer token in the request's Authorization header.

curl --request GET \
  --url https://api.mothership.com/beta/shipments/MS5016101 \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Content-Type: application/json'

Unauthenticated requests will fail with a 401 response code.

Unauthenticated 401 Responsejson

{
  "code": 401,
  "type": "UNAUTHENTICATED",
  "message": "Unauthorized"
}

A token that is valid but lacks permission for an endpoint gets a 403 with the type MISSING_PERMISSION. See Error handling.