Leadspace Authentication

generated: '2026-08-13'
method: searched
source: https://support.leadspace.com/hc/en-us/articles/23687993264284-Leadspace-Single-Direct-API-v4-Technical-Specifications
docs: https://support.leadspace.com/hc/en-us/articles/360000827409-API-v4-OAuth-2-0-Diagram
update_note: >-
  UPGRADE 2026-08-13. Leadspace now runs TWO unrelated authentication stacks.
  The enterprise v4 gateway (apigw.leadspace.com) is unchanged: a Leadspace-issued
  Program ID plus a perpetual bearer token, or an OAuth 2.0 resource-owner
  password-credentials exchange against the gateway. The new Leadspace MCP server
  (skprod.leadspace.com/mcp/v1) authenticates END USERS with OAuth 2.1
  authorization-code + PKCE against an Auth0 tenant, with dynamic client
  registration and RFC 9728 protected-resource metadata. A credential for one
  does not work on the other.
summary:
  types:
    - http
    - oauth2
  api_key_in:
    - header
  oauth2_flows:
    - password
    - authorizationCode
  transport: https-only
  credential_delivery: >-
    Leadspace issues a Program ID (username) and an authentication secret / API
    key out of band, by email, at program setup. A customer may hold multiple
    API keys, one per program.
schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    in: header
    parameter: Authorization
    format: "Authorization: Bearer API_KEY"
    description: >-
      Perpetual token issued by Leadspace at program setup. Used directly as a
      bearer credential on every enrichment, discovery, and intent request.
    sources:
      - openapi/leadspace-enrichment-openapi.yml
      - openapi/leadspace-discovery-openapi.yml
      - openapi/leadspace-intent-openapi.yml
  - name: oauth2
    type: oauth2
    flow: password
    description: >-
      Username-password (resource owner password credentials) flow. POST the
      Program ID as `user`, the authentication secret as `pass`, and the
      audience `API_GATEWAY` to the authorize endpoint to receive a bearer
      token plus a refreshToken. Tokens expire every 24 hours; refresh with a
      PUT to the same endpoint.
    tokenUrl: https://apigw.leadspace.com/oauth/authorize
    refreshUrl: https://apigw.leadspace.com/oauth/authorize
    token_ttl_seconds: 86400
    audience: API_GATEWAY
    scopes: []
    scopes_note: >-
      Leadspace does not document an OAuth scope surface; entitlement is bound
      to the Program ID rather than to per-request scopes.
    sources:
      - https://support.leadspace.com/hc/en-us/articles/360000827409-API-v4-OAuth-2-0-Diagram
  - name: mcp-oauth
    type: oauth2
    flow: authorizationCode
    applies_to: https://skprod.leadspace.com/mcp/v1
    protocol: OAuth 2.1
    pkce: S256
    description: >-
      Per-USER OAuth for the Leadspace MCP server. The MCP client is registered
      dynamically (RFC 7591) — Leadspace's own setup instructions say to leave
      the OAuth client ID and secret fields blank — then the user signs in with
      their Leadspace account (the same account as Leadspace Sidekick; a free
      account can be created self-serve with a work email).
    authorizationUrl: https://stg-sk.us.auth0.com/authorize
    tokenUrl: https://stg-sk.us.auth0.com/oauth/token
    registrationUrl: https://stg-sk.us.auth0.com/oidc/register
    jwks_uri: https://stg-sk.us.auth0.com/.well-known/jwks.json
    issuer: https://stg-sk.us.auth0.com/
    grant_types:
      - authorization_code
      - refresh_token
    token_endpoint_auth_methods:
      - none
      - client_secret_post
    bearer_methods_supported:
      - header
    realm: leadspace-builders
    scopes:
      - openid
      - profile
      - email
      - offline_access
    scopes_note: >-
      Identity scopes only — there is no Leadspace-defined authorization scope.
      Entitlement (plan tier, credit balance, which reveals are allowed) is
      enforced server-side against the account, not by the token. Detail in
      scopes/leadspace-scopes.yml.
    discovery:
      protected_resource_metadata: https://skprod.leadspace.com/.well-known/oauth-protected-resource
      authorization_server_metadata: https://skprod.leadspace.com/.well-known/oauth-authorization-server
      spec:
        - RFC 9728
        - RFC 8414
        - RFC 7591
    challenge_observed: 'WWW-Authenticate: Bearer realm="leadspace-builders", resource_metadata="https://skprod.leadspace.com/mcp/v1/.well-known/oauth-protected-resource"'
    sources:
      - https://www.leadspace.com/solutions/leadspace-mcp/claude
      - https://www.leadspace.com/solutions/leadspace-mcp/chatgpt
      - https://skprod.leadspace.com/.well-known/oauth-protected-resource
token_rotation:
  perpetual_token: true
  recommended_rotation_months: 6
  hard_expiry_years: 2
  process: >-
    Leadspace recommends rotating the perpetual token every six months from the
    end of the integration period. An unrotated token expires two years after
    issue. Leadspace generates the replacement, notifies the customer ahead of
    the end of the token lifecycle (10 working days' notice per the Discovery
    API docs), and deprecates the old token once migration is confirmed.
failure_modes:
  - status: 401
    meaning: Wrong credentials, or credentials have expired
  - status: 403
    meaning: Program ID is invalid (Discovery API)
  - status: 427
    meaning: Insufficient credits, or the program ID is invalid