Skip to main content
The Interstellas API authenticates every request using two headers: an API key and an API secret. There is no session or token exchange step — generate a key pair from the dashboard and start making requests.

​
Required headers

Every API request must include both of the following headers:
Most business endpoints also require a businessId header scoping the request to a specific business. See the API overview and individual endpoint pages for which headers each endpoint expects.
Do not send an Authorization: Bearer header alongside x-api-key / x-api-secret — requests that include both are rejected. Bearer tokens are used only by the Interstellas web dashboard and are not part of the API authentication scheme.

​
Key format

  • x-api-key values look like stl_ followed by 32 hexadecimal characters, e.g. stl_c8e286ca55b0123e0b05da047494f585.
  • x-api-secret values look like stl_test_ or stl_live_ followed by 64 hexadecimal characters.
There is no separate “mode” flag or environment header — the stl_test_ or stl_live_ prefix on your secret determines whether a request is treated as sandbox or production traffic. Live and test credentials are fully isolated from each other: they draw from separate rate-limit budgets and operate on separate data. A test key can never see or affect live data, and vice versa.

​
Generating and storing credentials

Generate an API key pair from the Interstellas dashboard under Settings → API Keys. The x-api-secret is shown to you exactly once, at the moment it’s created or regenerated — store it securely right away, since you won’t be able to view it again afterward. If you lose it, you’ll need to regenerate a new one, which invalidates the old secret.
Never expose your x-api-secret in client-side code, public repositories, or application logs. Treat it like a password.

​
Rotating and revoking keys

You can regenerate your x-api-secret or revoke an API key entirely from the dashboard at any time. Revocation takes effect within about 60 seconds — a key you’ve just revoked may continue to work briefly during that window, so don’t be alarmed if a request succeeds immediately after revoking.

​
Security best practices

  • Store credentials in environment variables — never hard-code them in source files.
  • Use stl_test_... credentials in development and stl_live_... credentials only in production.
  • Revoke and regenerate a key immediately if you suspect it has been compromised.
  • Grant keys only the scopes they need (see below).

​
Scopes

API keys carry a set of scopes, such as transfers:read, transfers:write, or customers:read. Where a scope check is enforced, a request made with a key that isn’t scoped for the endpoint it’s calling returns 403 Forbidden rather than 401 Unauthorized.
Every API key currently issued defaults to full access (["*"]), and no endpoint currently enforces per-scope checks. Scoping is part of the credential model but isn’t yet gating any endpoint — don’t build authorization logic in your integration around it until your account team confirms it’s enforced for the endpoints you use.

​
Rate limits

Rate limits are enforced per API client, per minute: Your tier is assigned to your account based on your contract with Interstellas — it isn’t self-service. Live and test credentials draw from separate rate-limit budgets, so testing against sandbox won’t consume your production allowance. Exceeding your limit returns 429, with a Retry-After header (seconds until you can retry):

​
Errors

A 401 is returned whenever a request can’t be authenticated. The message is one of two generic buckets — a missing/malformed request ("Unauthorized") or recognized-but-wrong credentials ("Invalid credentials") — neither of which reveals which specific header or value was the problem:
See Errors for the full error envelope, error codes, and authentication error reference.