Instant Commerce Authentication

generated: '2026-08-13'
method: searched
source: https://docs.instant.so/en/articles/16068062-access-tokens-and-mcp.md
description: >-
  Authentication profile for every Instant surface an external client can reach.
  There is no OpenAPI to derive securitySchemes from — derive-authentication.py
  returned zero profiles — so this artifact is built from the provider's own
  documentation plus live unauthenticated probes of api.instant.so. Instant has
  no OAuth flow, no OIDC discovery and no published API-key header convention;
  the single documented programmatic credential is a project-scoped access token
  presented as an HTTP bearer token to the MCP endpoint.
docs:
  - https://docs.instant.so/en/articles/16068062-access-tokens-and-mcp.md
  - https://docs.instantcommerce.io/developer/getting-started/authentication
schemes:
  - id: mcp-access-token
    type: http
    scheme: bearer
    surface: https://api.instant.so/mcp
    status: beta
    description: >-
      A long-lived access token created in the Instant dashboard under
      Settings → General → Access tokens. The full token is shown exactly once at
      creation and cannot be displayed again; the dashboard afterwards lists only
      a masked prefix, the creator, and the last-used timestamp.
    issuance:
      where: Instant dashboard → Settings → General → Access tokens → New token
      who_may_issue: Project owners and admins only.
      one_time_display: true
      naming: >-
        Each token is named for where it will be used (the docs use "Claude
        Desktop" as the example).
    scoping:
      granularity: project
      note: >-
        A token is scoped to the current project only, and is tied to the member
        who created it. If that member loses access to the project, their tokens
        for it are revoked automatically. The provider recommends one token per
        developer/client so individual tokens can be revoked in isolation.
      oauth_scopes: none
    revocation:
      where: Settings → General → Access tokens → token menu → Revoke
      immediate: true
      reversible: false
      note: >-
        Any client using a revoked token loses access immediately and revocation
        cannot be undone. Server-side enforcement confirmed by probe.
    evidence:
      - probe: POST https://api.instant.so/mcp (no Authorization header)
        status: 401
        body: '{"message":"Missing Authorization header","error":"Unauthorized","statusCode":401}'
      - probe: 'POST https://api.instant.so/mcp with Authorization: Bearer <invalid>'
        status: 401
        body: '{"message":"Invalid or revoked token","error":"Unauthorized","statusCode":401}'
        note: >-
          The distinct message proves the header name/scheme is
          `Authorization: Bearer <token>` and that revocation state is checked at
          request time.
    checked: '2026-08-13'
  - id: cli-interactive-login
    type: interactive
    surface: Instant CLI (@instantcommerce/cli)
    description: >-
      The CLI authenticates through an interactive login triggered by any command
      requiring store access (`instant login`), with `instant whoami`,
      `instant refresh` (refresh the access token), `instant select` (switch
      organization/storefront) and `instant logout` managing session state. The
      token format, endpoint and lifetime are not published.
    docs: https://docs.instantcommerce.io/developer/getting-started/authentication
  - id: storefront-sdk-none
    type: none
    surface: window.Instant.api (published storefront)
    description: >-
      The Instant Storefront SDK is an unauthenticated browser-side JavaScript
      API attached to the shopper's page by the Instant storefront script. It
      carries no credential and exposes no privileged operation — it toggles and
      refreshes the Instant cart UI and dispatches DOM events. Cart mutation is
      delegated to Shopify's own Ajax Cart API under the shopper's session.
    docs: https://docs.instant.so/en/articles/16068067-instant-storefront-sdk.md
absent:
  - scheme: oauth2
    note: >-
      No OAuth flow is documented and no OAuth metadata is served —
      /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource
      and /.well-known/oauth-protected-resource/mcp all return 404 on
      api.instant.so. MCP clients cannot perform dynamic client registration or
      an authorization-code flow; the user must paste a dashboard-issued token.
    checked: '2026-08-13'
  - scheme: openIdConnect
    note: /.well-known/openid-configuration returns 404 on every Instant host.
    checked: '2026-08-13'
  - scheme: mutualTLS
    note: Not documented on any surface.
    checked: '2026-08-13'
end_user_auth:
  note: >-
    Human sign-in to the Instant dashboard is email magic-link or Google, with no
    password, per the help center. This is end-user authentication, not an API
    credential, and is recorded for completeness only.
  docs: https://docs.instant.so/en/articles/16068137-create-your-account-and-sign-in.md