Skip to main content

Security

Encryption​

All communications are always encrypted end-to-end using HTTPS.

Authentication​

Authorization of the REST API calls is done using static credentials:

  • Client ID: your application's unique identifier
  • Client Secret: your application's secret key (never share this with anyone)

Authorization Header​

All REST API calls must include the Authorization HTTP header set as follows:

Authorization: Basic {base64-encoded credentials}

Where {base64-encoded credentials} is Base64Encode(clientID + ":" + clientSecret)

info

Starboard provides the credentials (Client ID and Client Secret), or your company's admins generate them in Starboard: see Keys and Companies.

Example​

If your credentials are:

  • Client ID: myClientId
  • Client Secret: myClientSecret

You would create the authorization header like this:

const credentials = 'myClientId:myClientSecret';
const encodedCredentials = btoa(credentials); // Base64 encode
const authHeader = `Basic ${encodedCredentials}`;

Then include this header in all API requests:

curl -X POST -H "Authorization: Basic bXlDbGllbnRJZDpteUNsaWVudFNlY3JldA==" \
     -H "Content-Type: application/json" \
     -H "X-User-Company-ID: {your-company-id}" \
     https://<your-starboard-api-host>/api/v2/test/auth

Keys and Companies​

  • Getting a key. If Starboard has turned on self-serve for your company, your company's admins generate keys in Starboard under Settings → Developer settings, in the API keys section, with up to 10 active keys at a time. Otherwise, contact your Starboard team for a key. A key's secret is shown only once, when the key is generated, so store it securely, like a password.
  • One key, one company. Each key acts for exactly one company. Send that company's ID in the X-User-Company-ID header, exactly as Starboard gave it to you: the match is case-sensitive. Any other value returns 401 Unauthorized, even with valid credentials.
  • To change a secret, switch to a new key. A key's secret can't be changed. Get a new key, deploy it, and then revoke the old one: both keys work until you revoke the old one, so you switch without a gap.
  • Revoking and deleting keys. With self-serve, your admins revoke a key under Settings → Developer settings, and can then delete it: a deleted key leaves the list, and Starboard keeps a record of it. Otherwise, ask your Starboard team to revoke a key.

Calling the API​

  • From your backend only. Call the API server to server. Browsers aren't supported: the API sends no CORS headers, and your secret must never reach a browser.
  • Allow time. Set your client timeout to at least 60 seconds. The first call after a quiet period can take noticeably longer while the service starts up.
  • Retry reads on 503 and 5xx, a few times. Retry GET requests with exponential backoff, a bounded number of times (for example, up to 5 attempts), then report the failure. 503 with "error": "unavailable" means your credentials couldn't be checked right now, not that they're wrong; only 401 means the credentials or company header are wrong.
  • Don't retry permanent 500s. Some 500s come from the request itself and fail the same way every time: a List Quotes filter (customer_company_id, rfq_id) or a List Contacts company_id that isn't a UUID, and the validation failures listed under Errors from CRM Writes. Fix the request instead.
  • Not every error is JSON. 429, 502, 504 and some 503 responses can come from the infrastructure in front of the API, without a JSON body. Treat them like 503: retry with backoff.