name: Nucleus Security Authentication
description: >-
  Nucleus Security authenticates three distinct surfaces three different ways: the tenant
  platform REST API with a static API key in an `x-apikey` header, both MCP servers with
  OAuth 2.1 authorization-code + PKCE, and the public vulnerability intelligence API with
  nothing at all.
generated: '2026-08-26'
method: searched
source: >-
  https://help.nucleussec.com/docs/api-access.md,
  https://help.nucleussec.com/docs/nucleus-mcp-server.md,
  https://help.nucleussec.com/docs/create-a-local-mcp-server-to-connect-to-nucleus-rest-apis.md,
  and probes of https://nucleussec.com/.well-known/oauth-authorization-server, 2026-08-26.
docs: https://help.nucleussec.com/docs/api-access

surfaces:
- surface: Nucleus Platform REST API
  base_url: https://[instance-name].nucleussec.com/nucleus/api
  scheme_type: apiKey
  scheme:
    type: apiKey
    in: header
    name: x-apikey
  evidence: >-
    The provider's own local-MCP walkthrough passes the credential verbatim as
    `EXTRA_HEADERS: "x-apikey: <OUR API KEY>"` against the Nucleus API base URL.
  key_types:
  - type: user_api_key
    description: >-
      Generated by any user holding the API Access permission, from User Profile >
      Generate API Key in the Nucleus console.
    expiration: >-
      No fixed expiry. A user's API key remains valid until they regenerate it, or until
      the user is deleted or disabled.
    rotation: Manual regeneration by the user; regenerating invalidates the previous key.
  - type: service_account_api_key
    description: >-
      Created by an organization administrator via Global Dashboard > Global
      Administration > Users > Add API Account. The account is API-only, is scoped to
      selected projects, and is assigned a role per project.
    expiration: Not stated by the provider.
    rotation: Not stated by the provider.
  authorization_model: >-
    Role-Based Access Control (RBAC) plus Asset Group Access Control (AGAC). A key inherits
    exactly the permissions of the user or service account that owns it, per project.
  interactive_docs: >-
    A Swagger UI with Authorize + Try it out is served inside the authenticated console at
    Help > API Docs. The swagger.yaml is downloadable from that page. Not publicly reachable.

- surface: Nucleus MCP Server (product)
  base_url: https://[your-nucleus-instance].nucleussec.com/nucleus/mcp
  scheme_type: oauth2
  scheme:
    type: oauth2
    flow: authorizationCode
  description: >-
    Authenticate with Nucleus account credentials and complete an on-screen authorization
    prompt in the AI client. Governed by a dedicated MCP permission in the Nucleus role
    model, enabled by default on out-of-the-box roles. MCP does not function if API access
    is disabled for the user or role. Enforces the same RBAC and AGAC as the console, at
    query time.
  evidence: https://help.nucleussec.com/docs/nucleus-mcp-server.md

- surface: Nucleus website MCP server
  base_url: https://nucleussec.com/wp-json/mcp/mcp-oauth-server
  scheme_type: oauth2
  scheme:
    type: oauth2
    flow: authorizationCode
    pkce: S256
    authorization_endpoint: https://nucleussec.com/oauth/authorize
    token_endpoint: https://nucleussec.com/oauth/token
    revocation_endpoint: https://nucleussec.com/oauth/revoke
    scopes: [mcp]
    token_endpoint_auth_methods: [none]
    grant_types: [authorization_code, refresh_token]
  discovery:
    authorization_server_metadata: https://nucleussec.com/.well-known/oauth-authorization-server
    protected_resource_metadata: https://nucleussec.com/.well-known/oauth-protected-resource
    rfc8414: true
    rfc9728: true
  bearer_methods_supported: [header]
  evidence:
    probed: '2026-08-26'
    unauthenticated_status: 401
    unauthenticated_body: '{"code":"mcp_unauthorized","message":"MCP authentication required."}'

- surface: Public Vulnerability Intelligence API
  base_url: https://nucleussec.com/wp-json/nucleussec/v1
  scheme_type: none
  description: >-
    No authentication. GET /vulnerabilities/list returns HTTP 200 with data to any
    anonymous caller. Verified 2026-08-26.

console_authentication:
  sso:
    supported: true
    protocols: [SAML 2.0]
    identity_providers:
    - Generic SAML
    - Okta
    - Microsoft Entra ID (formerly Azure AD)
    modes: [Self-Serve SAML, Support Assisted SAML]
    group_mapping: >-
      SSO groups/roles from Okta and Entra ID can be mapped to Nucleus role-project
      combinations.
    docs: https://help.nucleussec.com/docs/sso
  scim:
    supported: false
    note: No SCIM provisioning documentation was found in the public help center.

gaps:
- >-
  No published OpenAPI securitySchemes block for the platform API - the Swagger definition
  itself is behind the customer console login, so the auth profile above is transcribed
  from prose documentation rather than derived from a machine-readable contract.
- API key expiry and rotation policy for service accounts is not documented.
- No mutual TLS, no OpenID Connect discovery document, and no client-credentials grant.