Adapter Authentication

Credentials at a glance

An adapter installation has two distinct secrets. They flow in opposite directions, which is the usual source of confusion:

The authorization header value and the launch keyset are unrelated key material and rotate independently.

ChartHero-to-partner requests

ChartHero authenticates to your adapter endpoints with the authorization header value saved on the adapter installation. During setup, the value can be generated in ChartHero and copied into your adapter service, or pasted from a partner-supplied secret. In both cases, ChartHero stores the value and sends the external_api credential verbatim as the Authorization header value — including any scheme prefix you choose:

Authorization: Bearer <partner_issued_token>
X-ChartHero-Contract-Version: 1.0
X-ChartHero-Request-Id: req_01JZ123456789ABCDEFGHJKLM

Authorization: ApiKey <partner_issued_token>

Authorization: <partner_issued_token>

If your system expects Bearer (or ApiKey, Token, …), include that prefix in the stored value; ChartHero does not add or remove one.

The authorization header value authenticates ChartHero when ChartHero calls your system. It is not a ChartHero public API key and should not be used to call ChartHero.

Do not require credentials in query parameters or request bodies. Return 401 unauthorized when the Authorization header value is missing or invalid. Return 403 forbidden when the Authorization header value is valid but cannot use the requested adapter endpoint.

Launch keysets

Launch links use separate key material from the authorization header value. A launch keyset lets your system encrypt launch payloads that ChartHero decrypts during browser launch.

{
  "version": 1,
  "keys": [
    {
      "kid": "launch-key-2026-06",
      "kty": "oct",
      "alg": "dir",
      "enc": "A256GCM",
      "status": "active",
      "k": "uF5t2qLGVMrT8zmQhC9aH0-7pQWBIJEPVwNXAXEuwpA"
    }
  ]
}

Rules:

1. Each key is a cryptographically random 32-byte symmetric key encoded with base64url. Do not reuse the example key.
2. The JWE protected header kid must match one configured key.
3. Exactly one key is active at a time.
4. Use a new kid during rotation.
5. Each key entry must include kid, kty, alg, enc, status, and k. kty must be oct, alg must be dir, and enc must be A256GCM.
6. Never place key material in launch URLs, logs, normal API responses, or support tickets.

ChartHero can generate the launch keyset during setup and show the key material once for secure handoff into your launch issuer. Partner-supplied keysets may be imported when required by the organization.

Rotation

Rotate launch keys through the launch-keyset credential, not by making two keys active inside one keyset. Each keyset must still contain exactly one active key.

During rotation, ChartHero creates or accepts a new active launch_keyset credential with a new active kid and keeps the previous credential in a retiring overlap window. Move launch-link creation to the new active kid when rotation begins. Launch resolution can use active keys from both current and retiring credential rows during the overlap window, so recently issued links using the old kid can expire naturally. Retired entries inside a keyset are ignored for encrypted-launch decryption.

Do not reuse a kid across overlapping launch-keyset credentials. After the overlap window, let the old credential expire or be revoked according to the coordinated rotation plan.

Authorization header value rotation is separate from launch-key rotation. Rotating one does not automatically rotate the other.