Authentication
The Explore API supports two ways for users to authenticate, plus an API key you send on every authenticated request. Full detail lives in the Telmar API Authentication docs.
Login methods
| Method | How it works |
|---|---|
| Standard login | Users authenticate with their TelmarHelixa Explore Cognito username and password, provided by Sales. |
| SSO / federated login | SSO for API calls via OAuth 2.0, SAML 2.0 and OpenID Connect (OIDC). Supported identity providers include Google, Microsoft, Okta, and any domain with SSO auth access enablement. |
The Developer Portal is accessed via Cognito login only — SSO is not currently enabled for portal access. SSO is available for API calls themselves.
Portal auth vs API auth
These two are the most common source of confusion, so it is worth being explicit.
| Developer Portal auth | API auth | |
|---|---|---|
| Who it identifies | A person | A machine client / integrating service |
| Credential | Cognito username + password | API key (Telmar-Engine-Authorizer) |
| What you send | A browser session after Cognito sign-in | Telmar-Engine-Authorizer: <api-key> |
| SSO | Not enabled for the portal today | Available (OAuth 2.0, SAML 2.0, OIDC) |
| Used for | Retrieving your API key, viewing Swagger docs | Calling POST /crosstab |
| Scoped by | Your portal account | Licensed datasets and survey permissions |
The practical consequence: a person signs in to the portal to retrieve an API key, and your application uses that key to call the API. A portal session cookie alone cannot call the API.
Prerequisites
All API users require a TelmarHelixa account with data access enabled for their licensed datasets. Permissioning and survey access must be configured before any API queries can be made — see Getting started → Permissioning.
Sending the API key
Authenticated requests send the key from the Developer Portal as:
Telmar-Engine-Authorizer: SAMPLE.ENGINE.AUTHORIZER
GET /docs and OPTIONS /crosstab do not require this header. POST /crosstab
does.
Store the API key in a secret manager. Never commit it, never ship it to a browser. Rotate it in the portal if it is exposed.
Failure modes
| Symptom | Cause | Fix |
|---|---|---|
401 Unauthorized | API key or Cognito credentials missing, malformed or invalid | Verify the key from the Developer Portal; see the auth docs |
401 on every call, always | Sending a portal session cookie instead of the API key | Use Telmar-Engine-Authorizer — see above |
403 Forbidden | Valid credentials, but no access to the requested dataset | Confirm survey permissioning with TelmarHelixa |
Works locally, 401 in CI | CI is using a stale or unset secret | Check your CI secret store |
Worked request and response payloads for the 401 and 403 cases are in the
example gallery.
Security expectations
- Store the API key in a secret manager. Never commit it, never ship it to a browser.
- Rotate credentials if a secret is exposed.
- Use separate credentials per environment so revoking one does not take down the other.
- Ensure every caller has a TelmarHelixa account with the right licensed datasets enabled.