Landbase Authentication

generated: '2026-08-23'
method: searched
source: >-
  https://www.landbase.com/docs/reference/auth,
  https://www.landbase.com/docs/explanation/platform-vs-legacy,
  https://www.landbase.com/docs/reference/config-files,
  https://www.landbase.com/docs/reference/env-vars,
  https://www.landbase.com/docs/how-to/troubleshoot-auth, plus the OIDC discovery document probed at
  https://api.landbase.com/.well-known/openid-configuration.
description: >-
  Landbase runs two authentication models side by side, and which one you get depends on a mode
  switch rather than a per-credential choice. Platform mode (the default) is a browser OAuth consent
  flow that mints a short-lived session token; legacy mode is a long-lived API key that bypasses the
  gateway entirely and speaks to the AgentOS backend directly. Both are documented for the CLI. No
  OpenAPI securitySchemes exist to derive from — this profile is read from the provider's own auth
  pages and from the one machine-readable artifact on the estate, the OIDC discovery document.
base_url: https://api.landbase.com
docs: https://www.landbase.com/docs/reference/auth
schemes:
  - id: platform-oauth-session
    type: oauth2
    default: true
    name: Platform session (OAuth)
    flow: >-
      Browser authorization-code style consent. `landbase-cli auth login` opens a consent page; if
      the caller is not signed in they are sent to https://gtm.landbase.com to sign in or create an
      account, then approve the CLI access request. In a headless or SSH environment the CLI prints
      the URL to stderr instead of opening a browser.
    token_prefix: lbs_
    token_ttl: >-
      7 days — stated in the contacts-import error table ("The platform session expired (7-day TTL)
      — re-login"). The stored session also carries an explicit expiresAt.
    stored_at: ~/.landbase/platform.json (mode 0600)
    stored_fields: [accessToken, expiresAt, accountId, deviceName]
    routed_through: https://api.landbase.com (the cloud gateway)
    reauth: landbase-cli auth login --force
    scopes_published: false
    scopes_note: >-
      The consent page grants "CLI access" as a single undifferentiated approval. Landbase publishes
      no scope or permission reference, no scope strings appear anywhere in the documentation, and
      there is no /.well-known/oauth-authorization-server (404) to read them from — so no
      scopes/ artifact could be derived. An agent cannot request or verify least privilege.
  - id: legacy-api-key
    type: apiKey
    default: false
    name: Legacy API key
    key_prefix: lbk_
    stored_at: ~/.landbase/config.json (mode 0600, field apiKey)
    env_var: LANDBASE_API_KEY
    env_precedence: LANDBASE_API_KEY wins over the key stored in config.json.
    created_by: landbase-cli auth login --key
    enable_with: LANDBASE_LEGACY_MODE=1
    routed_through: AgentOS backend directly, bypassing the api.landbase.com gateway
    rotation: >-
      Documented as safe to edit the apiKey field in config.json directly to rotate a key without
      re-running auth login. No expiry is stated — these are described as long-lived.
    intended_use: >-
      Backward compatibility and non-interactive/CI use. The FAQ recommends the API key for CI,
      scripts and remote servers because the OAuth flow needs a browser.
    status: legacy — Landbase tells new users to stay on platform mode.
oidc:
  discovery_url: https://api.landbase.com/.well-known/openid-configuration
  status: 200
  issuer: platform.landbase.com
  jwks_uri: /.well-known/jwks.json
  jwks_status: 200
  signing_algs: [RS256]
  key_ids: [platform-jwt-1]
  conformant: false
  conformance_note: >-
    The document is a three-field stub. OpenID Connect Discovery 1.0 requires
    authorization_endpoint, token_endpoint, response_types_supported and subject_types_supported;
    none is present, and jwks_uri is a relative path rather than the absolute URL the spec
    mandates. It is enough to verify a platform JWT's signature and nothing else — a relying party
    cannot drive a login from it. See conformance/landbase-conformance.yml.
transport:
  tls_required: true
  base_url_allowlist: >-
    LANDBASE_API_BASE_URL is constrained to *.landbase.com, localhost or 127.0.0.1 unless
    LANDBASE_ALLOW_CUSTOM_API_URL=1 is set, and the installer applies the same allowlist to
    LANDBASE_INSTALL_URL. This is a deliberate anti-exfiltration control on a credential-bearing
    client and is worth crediting.
errors:
  - {code: AUTH_FAILED, exit: 3, meaning: No valid API key or session, or the credentials were rejected.}
  - {code: AUTH_REQUIRED, exit: 3, meaning: "Interactive login required (contacts-import surface)."}
  - {code: SETUP_FAILED, exit: 1, meaning: A configuration step failed, e.g. a config permissions write.}
diagnostics: landbase-cli doctor
troubleshooting: https://www.landbase.com/docs/how-to/troubleshoot-auth