Blnkfinance Authentication

generated: '2026-08-27'
method: searched
source: >-
  https://docs.blnkfinance.com/advanced/configuration/server-security,
  https://docs.blnkfinance.com/api-keys/overview, https://docs.blnkfinance.com/api-keys/scopes,
  https://docs.blnkfinance.com/cloud/auth/api-keys, https://docs.blnkfinance.com/cloud/reference/mcp,
  https://api.cloud.blnkfinance.com/.well-known/oauth-authorization-server (HTTP 200),
  openapi/blnkfinance-core-openapi.json
note: >-
  UPGRADED FROM DERIVED. The published OpenAPI declares a single securityScheme -- http/basic -- and
  applies it nowhere. That is wrong about the shipped product: every documented Core call authenticates
  with the X-Blnk-Key header, and Blnk Cloud uses Bearer with API keys or OAuth 2.0. The spec's
  http/basic scheme is recorded below as spec_declares for provenance, but the surfaces[] block is what
  an integrator should read.
summary:
  types: [apiKey, http, oauth2]
  primary: X-Blnk-Key header (Core), Bearer token (Cloud)
spec_declares:
  file: openapi/blnkfinance-core-openapi.json
  schemes:
  - {name: basic, type: http, scheme: basic}
  applied_to_operations: 0
  discrepancy: >-
    The spec neither declares the X-Blnk-Key apiKey scheme nor applies any security requirement to its
    18 operations. Generated clients built from this spec will emit no auth header at all.
surfaces:
- surface: Blnk Core REST API (self-hosted)
  base: http://localhost:5001 (default; operator-chosen in production)
  schemes:
  - name: blnk-key
    type: apiKey
    in: header
    header: X-Blnk-Key
    accepts:
    - kind: master key
      value_source: BLNK_SERVER_SECRET_KEY
      privileges: full access; the only key that can manage hooks or act across owners
    - kind: scoped API key
      value_source: created via the API key endpoints
      privileges: 'resource:action scopes (see scopes/blnkfinance-scopes.yml)'
      expiry: supported (expires_at)
      owner_context: 'keys carry an owner; non-master keys are confined to their own owner_id'
      storage: hashed at rest since Core 0.12.0; encrypted with AES-256-GCM per the security page
  enforcement_flag:
    key: BLNK_SERVER_SECURE
    default: false
    behavior: >-
      When false Blnk SKIPS authentication checks entirely. Authentication is only enforced when the
      operator sets it to true, which the docs call out as a required step for "any real deployment".
      This is the single most important thing an integrator must know about Blnk Core auth: the shipped
      default is open.
  errors:
  - {code: AUTH_MISSING_API_KEY, status: 401}
  - {code: AUTH_INVALID_API_KEY, status: 401}
  - {code: AUTH_EXPIRED_API_KEY, status: 401}
  - {code: AUTH_INSUFFICIENT_PERMISSIONS, status: 403}
  - {code: AUTH_MASTER_KEY_REQUIRED, status: 403}
  - {code: AUTH_CROSS_OWNER_ACCESS, status: 403}
  - {code: AUTH_SCOPE_ESCALATION, status: 403}
  docs: https://docs.blnkfinance.com/api-keys/overview
- surface: Blnk Cloud REST API
  base: https://api.cloud.blnkfinance.com
  schemes:
  - name: bearer-api-key
    type: http
    scheme: bearer
    header: 'Authorization: Bearer <api key>'
    docs: https://docs.blnkfinance.com/cloud/auth/api-keys
  - name: oauth2
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: https://api.cloud.blnkfinance.com/oauth/authorize
        tokenUrl: https://api.cloud.blnkfinance.com/oauth/token
        refreshUrl: https://api.cloud.blnkfinance.com/oauth/token
        pkce: [S256, plain]
    grant_types: [authorization_code, refresh_token]
    client_auth: [client_secret_post, client_secret_basic]
    metadata:
      rfc8414: https://api.cloud.blnkfinance.com/.well-known/oauth-authorization-server
      openid_configuration: https://api.cloud.blnkfinance.com/.well-known/openid-configuration
      http_status: 200
      probed: '2026-08-27'
      note: >-
        The two documents are byte-identical and neither advertises an id_token, jwks_uri, userinfo
        endpoint or scopes_supported -- so despite the /.well-known/openid-configuration path this is
        plain OAuth 2.0 authorization-code, not OpenID Connect. Do not treat it as an OIDC provider.
    docs: https://docs.blnkfinance.com/cloud/auth/oauth
  unauthenticated_behavior:
    status: 401
    body: '{"error":"Authorization header is required"}'
    note: Every path on api.cloud.blnkfinance.com returns this except the two OAuth metadata documents.
- surface: Blnk Cloud MCP (ledger)
  base: https://api.cloud.blnkfinance.com/mcp/{instance_id}
  schemes:
  - name: bearer
    type: http
    scheme: bearer
    accepts: [Blnk Cloud API key, OAuth 2.0 access token]
    required_scopes: ['mcp:read', 'mcp:write']
  docs: https://docs.blnkfinance.com/cloud/reference/mcp
- surface: Blnk docs MCP
  base: https://docs.blnkfinance.com/mcp
  schemes:
  - {name: none, type: none}
  note: Open, no authentication. Documentation search only.
- surface: Prometheus metrics
  base: GET /metrics on the Core API port and worker monitoring port
  schemes:
  - name: metrics-bearer
    type: http
    scheme: bearer
    value_source: BLNK_METRICS_BEARER_TOKEN
  access_matrix:
  - {secure: false, token_set: false, access: open}
  - {secure: false, token_set: true, access: bearer required}
  - {secure: true, token_set: true, access: bearer required}
  - {secure: true, token_set: false, access: blocked}
  docs: https://docs.blnkfinance.com/advanced/configuration/server-security#metrics-endpoint
secrets_note: >-
  BLNK_SERVER_SECRET_KEY is BOTH the master API key and the HMAC signing secret for outgoing webhooks
  and hook callbacks. Rotating it invalidates request auth and breaks webhook signature verification on
  every receiver at the same time.
mtls: false
openid_connect: false