Authentication and institution access

Telemetry requests use a bearer credential issued by a Teria administrator:

Authorization: Bearer <credential_id>.<secret>
Content-Type: application/json

The credential authorizes one institution within a Customer Account. V3 derives the account and originating institution from that credential. The API deployment determines environment and accepts only credentials for that environment. A direct institution has its own Customer Account and does not need a parent organisation. Central integrations must separate submissions by institution and use each institution's credential.

Omit organization_id, environment and event connected_institution_id in new V3 requests. Existing V3 integrations may continue supplying those fields as compatibility assertions: any supplied value must match the credential's scope. They cannot select another account or originating institution. Direct institutions omit organisation and connection assertions. V1 and V2 retain their existing required scope fields.

Obtain and store a credential

Your Teria administrator explicitly enables telemetry access and issues the credential. The secret is shown once to the issuing administrator and delivered through a secure channel, separately from the integration guide. If the secret is lost, request a replacement; it cannot be retrieved again.

Store the credential in your integration's secret store. Keep it out of URLs, browser storage, source control, screenshots, shared Postman collections and application logs. A downloadable example never includes a usable credential.

Credentials do not automatically expire. They remain valid until revoked or retired through rotation, subject to institution access being enabled. Sandbox credentials cannot be used in production. Production access uses a separate environment and credentials.

Rotate without interrupting delivery

Ask your Teria administrator to issue a replacement credential. The current credential and one replacement can overlap for up to 24 hours. Move your integration to the replacement, verify delivery, and ask the administrator to confirm cutover so the old credential is retired sooner. The replacement does not automatically expire.

Keep buffered event IDs and content unchanged during credential rotation. Replacing the credential does not create a new event namespace for the same Customer Account, institution and environment.

Pause and revocation

Pausing telemetry blocks new submissions while retaining the credentials. Resume with the same credential once the administrator restores access. Events already accepted continue processing, and existing data remains accessible.

Revocation permanently invalidates a credential for new requests. An administrator can revoke one credential or all credentials for an institution and environment. Restoring access after revocation requires a new credential. Keep events buffered while the issue is resolved, subject to the seven-day event-age limit.

Verify the connection

GET /v1/telemetry/connection accepts the same bearer credential and returns the authorised Customer Account, canonical institution and environment without submitting telemetry:

curl --request GET \
  --url https://sandbox.teriahq.com/v1/telemetry/connection \
  --header "Authorization: Bearer $TERIA_INGESTION_CREDENTIAL"

A successful response returns 200 OK:

{
  "account_id": "example-account",
  "institution_id": "example-origin",
  "organization_id": "example-organization",
  "connected_institution_id": "example-institution",
  "environment": "sandbox",
  "verified": true
}

For a direct institution, organisation and connection metadata are null:

{
  "account_id": "example-direct-account",
  "institution_id": "example-origin",
  "organization_id": null,
  "connected_institution_id": null,
  "environment": "sandbox",
  "verified": true
}

These response identifiers describe the credential's scope; do not copy them into the V3 request. This records connection verification. Submit an outcome and confirm processing to complete the end-to-end integration check.

Visibility and support

Customer administrators can view scoped credential metadata and integration status. Operators and viewers can view integration health in their workspace. Credential issuance, rotation, revocation, pause and resume remain with Teria administrators and are audited.

For an authentication issue, share the credential identifier, environment and a request reference with your Teria administrator. Never share the secret in a support message. See Errors and limits for the distinction between invalid credentials, paused access and scope mismatches.