Zum Hauptinhalt springen

Security

Embedding the iframe in production requires a clear understanding of the two credentials we issue and how to keep the public-facing one safe.

The two keys​

When you receive credentials, you get two distinct keys:

  • Iframe key (company identifier): used in the iframe URL as ?company=XXX.
  • S2S API token: used for server-to-server requests (fetching diagnostic reports, generating temporal keys, etc.).

The iframe key travels in plain text inside the URL. On a web page, anyone inspecting the DOM can read it. The risk is lower on native mobile apps where the URL is not directly inspectable, but the principle still applies: treat the iframe key as a public credential and rotate it through short-lived alternatives wherever possible.

The S2S API token, by contrast, must never leave your backend.

Temporal company identifiers​

To prevent unauthorised use of your iframe key, the API lets you generate short-lived temporal keys. Using the S2S API token, your backend creates a fresh company identifier for each iframe load and gives it a short expiry (for example 10 minutes). Even if the temporal key is intercepted, it becomes invalid quickly.

Endpoint​

  • Method: POST
  • Path: /company-app-keys
  • Full URL: your S2S Company API base URL + /company-app-keys (e.g. https://api.example.com/s2s/v3/company/company-app-keys)

Required headers​

  • X-API-TOKEN: <your S2S API token>
  • accept: application/json

Request body​

  • appKey: the app key value you want to register. Must be at least 64 alphanumeric characters. Generate it with a cryptographically secure random source.
  • expiresAt: expiry date/time in ISO-8601 format (e.g. 2026-12-31T23:59:59+00:00).
{
  "appKey": "my-secure-app-key-that-is-at-least-64-characters-long-1234567890abcdef",
  "expiresAt": "2026-12-31T23:59:59+00:00"
}

Example cURL​

curl -X POST "https://api.example.com/s2s/v3/company/company-app-keys" \
  -H "X-API-TOKEN: YOUR_S2S_TOKEN" \
  -H "accept: application/json" \
  -d '{
    "appKey": "my-secure-app-key-that-is-at-least-64-characters-long-1234567890abcdef",
    "expiresAt": "2026-12-31T23:59:59+00:00"
  }'

Success response​

HTTP 201 Created:

{
  "success": true,
  "message": "App Key created",
  "data": {
    "appKey": "my-secure-app-key-that-is-at-least-64-characters-long-1234567890abcdef",
    "expiresAt": "2026-12-31T23:59:59+00:00"
  },
  "errorCode": null
}

Using the generated key in the iframe URL​

The appKey returned in the response is the value you put in the iframe's company query parameter:

<iframe src="https://iframe.legit.health/?company=APP_KEY_FROM_RESPONSE"></iframe>

In short, the workflow is:

For the full list of parameters that can accompany company in the URL, see the Customize page.

Next Steps​

  • Customize the iframe appearance or behavior? See the Customize page.
  • Ready to embed on your platform? See the Platforms section.
  • Need to handle callbacks after analysis? See the Callbacks section.