Documentation

Access Keys

View as Markdown

Use Settings > Access Keys to create account-level credentials for supported Clear Ideas integrations. These keys are designed for governed external access, with explicit scope, optional expiration, and immediate revocation.

What This Page Covers

The account-level access key flow currently covers:

  • MCP keys for Model Context Protocol integrations
  • Webhook keys for inbound workflow webhook authentication

This page does not cover Site-level Public Chat widget keys. Those are created and managed from the Site's Public AI Chat settings.

Account-Level Keys vs Site-Level Widget Keys

Clear Ideas has two distinct key-management paths:

  • Account-level access keys are created from Settings > Access Keys
  • Site-level widget keys are created from Site Settings > Public AI Chat

Use the account-level flow when an external tool needs governed access to MCP or AI Workflow webhook endpoints. Use the Site-level flow when you are embedding Public AI Chat on a website.

Available Key Types

MCP Keys

MCP keys are used by supported assistants and coding tools to request permission-aware access to approved documents in Clear Ideas.

Read-scoped MCP keys can list sites, browse content, inspect metadata, list recent content, search, retrieve context, retrieve file text or summaries, and inspect version metadata. Write-scoped MCP keys can create files, create new file versions, and create folders when the user's site role and the site's read-only state allow it.

MCP access also depends on:

  • the account having AI and MCP access enabled
  • the target Site allowing MCP access
  • the user already having permission to the Site content
  • the target Site not being read-only for write operations

See Model Context Protocol.

Webhook Keys

Webhook keys are used to authenticate inbound requests that trigger AI Workflow jobs through webhook-based automation.

Webhook integrations should be scoped only to the workflows and webhook actions they actually need.

See AI Workflow Webhooks.

Create an Access Key

From Settings > Access Keys:

  1. Click New Access Key
  2. Enter a descriptive name
  3. Choose the key type
  4. Select the required scopes
  5. Optionally add an expiration date
  6. Create the key and copy the secret immediately

The full secret is shown only once at creation time.

Manage Existing Keys

The access-key list shows the operational details you need for review and cleanup, such as:

  • key type
  • scopes
  • status
  • created date
  • expiration date, if any
  • last-used information, when available

If a key is no longer needed, revoke it. Revocation is immediate and permanent.

Scope Guidance

Choose the narrowest scope set that still supports the integration.

For webhook integrations

Use only the webhook-related scope required for the workflow trigger path you are exposing.

For MCP integrations

Scope access so the external assistant can reach only the approved content and capabilities it actually needs.

  • Use read scope for discovery, metadata, search, retrieval, summaries, recent-content review, and version inspection.
  • Add write scope only when the integration needs to create files, create versions, or create folders.

Security Practices

  • Store keys in a secure secret store or password manager.
  • Use separate keys for separate environments or integrations.
  • Add expiration dates for temporary or partner-managed access.
  • Review last-used data and revoke stale keys.
  • Revoke immediately if exposure is suspected.