Authentication

How to obtain and use your API token to authenticate every request to the Upper Crew API.

Every request to the Upper Crew API must prove who it comes from. The API uses a static token — called the API Token — that you send as an HTTP header. There are no OAuth flows or session cookies: attach the header, and the API identifies your account.

How authentication works

Include the following header on every request to any ext-* endpoint:

x-api-token: <your token>

The API looks up the token against your account and confirms your account is active. If both checks pass, the request proceeds. If either fails, the API returns an error immediately — no part of the operation runs.

Your API token grants full programmatic access to your Upper account. Treat it like a password: never commit it to source control, never share it in public channels, and rotate it if you suspect it has been exposed.

Get your API token

Sign in to the Upper web app at crew.upperinc.com.
Open Settings from the left sidebar.
Navigate to Webhooks.
Locate the API Token field. Click the copy button next to it to copy the token to your clipboard.

The same screen is also where you register the URL that Upper will call when webhook events fire. The API token and webhook URL are managed together in one place.

Error responses

Missing token

If the x-api-token header is absent from a request, the API returns HTTP 400:

{
  "code": 400,
  "message": "Token is required.",
  "data": []
}

Invalid or unknown token

If the header is present but the token does not match any active account, the API returns HTTP 401:

{
  "message": "User not found.",
  "data": []
}

Both error responses use the standard response envelope { "code", "message", "data" } documented in the API overview. The 401 body mirrors this shape — check message to distinguish it from a 400.

Example authenticated request

The snippet below shows the minimum required header attached to a generic GET request. Replace <your token> with the value you copied from Settings.

curl -X GET "https://teamapi.upperinc.com/api/v1/ext-route-list" \
  -H "x-api-token: <your token>" \
  -H "Accept: application/json"

All API endpoints share the same base URL (https://teamapi.upperinc.com/api/v1) and the same header requirement — only the path and request body differ per operation.