Franklin Whole Home Authentication

generated: '2026-08-16'
method: searched
source: openapi/franklin-whole-home-openapi.yml
docs: https://api.franklinwh.com/
references:
- https://api.franklinwh.com/
- https://www.franklinwh.com/blog/introducing-the-franklinwh-api
summary:
  types:
  - apiKey
  api_key_in:
  - header
  oauth2_flows: []
  model: credential-pair exchanged for an opaque token
schemes:
- name: AuthorizationToken
  type: apiKey
  in: header
  parameter: Authorization
  description: Token returned by POST /api-common/tokenizer (exchange of a `cp` / `ck` credential
    pair). Sent as the raw Authorization header value with no `Bearer ` prefix.
  sources:
  - openapi/franklin-whole-home-openapi.yml
token_issuance:
  operation: tokenizer
  method: POST
  path: /api-common/tokenizer
  credentials:
  - name: cp
    required: true
    note: Credential pair identifier issued to the partner.
  - name: ck
    required: true
    note: Credential pair key issued to the partner.
  security: none
  note: The token endpoint is the only unauthenticated operation in the API.
  lifetime: not published
  refresh: Re-call the same operation; the portal labels it "Update Token".
failure_modes:
- code: 401
  http_status: 200
  msg: wrong token
  note: Token present but invalid or expired. Returned inside a HTTP 200 body.
- code: 403
  http_status: 200
  msg: missing token or token param
  note: Token absent, or cp/ck omitted on the token request. Returned inside a HTTP 200 body.
onboarding:
  model: partner-approval
  sso: FleetView single sign-on — installers sign in with an existing FleetView account
    (https://energy.franklinwh.com/) and the API portal applies the associated device scope,
    avoiding a duplicate account.
  audience: Authorised partners only — third-party system owners and financiers, large and midsize
    installers, and third-party service providers.
  url: https://www.franklinwh.com/apply?role=installer
scopes:
  model: implicit
  note: >-
    No OAuth 2.0 and no scope surface. FranklinWH states the API offers "flexible, granular
    permission controls" and that the portal applies the device scope attached to the FleetView
    account, but publishes no scope, permission or role vocabulary — access is bound to the
    credential pair rather than requested per call. scopes/ is therefore not emitted.
transport_security:
  tls_claim: TLS 1.3
  tls_observed: TLSv1.3
  observed_hosts:
  - test-api.franklinwh.com
  - api.franklinwh.com
  key_storage_claim: FranklinWH states API keys are stored as hashes rather than plaintext.
  source: https://www.franklinwh.com/blog/introducing-the-franklinwh-api
gaps:
- No published token lifetime, expiry semantics or refresh policy.
- No OIDC or OAuth 2.0 metadata — /.well-known/openid-configuration and
  /.well-known/oauth-authorization-server return 404 on every host.
- Authentication and authorisation failures are signalled inside a HTTP 200 body, so standard HTTP
  client auth handling will not fire.