API key authentication allows trusted MCP-compatible clients, backend services, and automation workflows to connect securely to the BoldDesk MCP Server. The API key identifies the licensed BoldDesk agent who generated it. When an MCP client submits a request, BoldDesk validates the API key and applies the agent’s roles, permissions, and accessible-brand scope before allowing the requested MCP operation.

API key authentication is recommended for:

• Trusted backend services
• Scheduled jobs
• Service-to-service integrations
• Internal automation workflows
• Development environments where credentials can be stored securely
• Non-interactive workloads that do not require user consent

Prerequisites

Before configuring API key authentication, ensure that:

• The Model Context Protocol is enabled in BoldDesk.
• API Key Authentication is enabled in the MCP configuration.
• A licensed BoldDesk agent account is available.
• The agent has the Manage API Keys permission.
• The MCP-compatible client supports connections to remote MCP servers.
• The MCP-compatible client can store the API key securely.
• The correct BoldDesk MCP endpoint is available.

How API Key Authentication Works

API key authentication uses an API key generated by a licensed BoldDesk agent to authenticate MCP requests.

The authentication process works as follows:

1. A licensed BoldDesk agent generates an API key from the agent’s profile settings.
2. The API key is added to the MCP-compatible client’s configuration.
3. The client includes the API key when connecting to the BoldDesk MCP Server.
4. The MCP Server validates the API key.
5. BoldDesk identifies the agent who generated the API key.
6. The agent’s roles, permissions, accessible brands, and resource scope are applied.
7. The MCP Server checks whether the requested operation is available through an exposed MCP tool.
8. The request is processed only when the API key is valid, the agent has the required access, and the operation is supported.

Requests made with an invalid, disabled, revoked, or expired API key are rejected.

User Scope and Permissions

The API key does not provide unrestricted access to BoldDesk. MCP requests are evaluated using the permissions and access scope of the agent who generated the API key.

Depending on the agent’s permissions and the tools exposed by the BoldDesk MCP Server, an MCP-compatible client may be able to work with supported resources such as:

• Brands
• Tickets
• Ticket conversations
• Forms and ticket fields
• Contacts and contact groups
• Agents
• Groups
• Ticket statuses
• Approval workflows

For example:

• If the agent cannot access a brand, an MCP client using that agent’s API key cannot access tickets belonging to that brand.
• If the agent cannot update a ticket, the API key does not allow the MCP client to bypass that restriction.
• If an operation is not exposed through a BoldDesk MCP tool, the client cannot perform the operation even if the agent can perform it in the BoldDesk application.

MCP-Compatible Clients

An MCP-compatible client is an AI assistant, development environment, autonomous agent, or application that supports the Model Context Protocol and can connect to a remote MCP server.

The method used to add the MCP endpoint and API key varies by client. Refer to the setup instructions for the selected MCP-compatible client.

Enable API Key Authentication for MCP

An administrator must enable API key authentication before MCP-compatible clients can use API keys to connect to the BoldDesk MCP Server.

To enable API key authentication:

1. Sign in to BoldDesk.

2. Go to AI > AI Agent & Tools > MCP Server.

3. Ensure that Model Context Protocol is enabled.

4. Locate API Key Authentication under the available authentication methods.

5. Turn on API Key Authentication.
   

   
   
   

After API key authentication is enabled, trusted clients and backend services can authenticate using active BoldDesk API keys.

Generate an API Key

To generate an API key, explore Generate and Manage API Keys in BoldDesk. MCP requests made using the API key are associated with the agent who generated it.

Configure the MCP-Compatible Client

Add the BoldDesk MCP endpoint and API key to the MCP-compatible client’s configuration.

The exact configuration depends on the selected client. Where supported, store the API key in:

• An environment variable
• An operating system credential store
• A secrets-management service
• Another secure server-side configuration mechanism

An MCP client configuration commonly requires:

• MCP server name: A recognizable connection name, such as bolddesk
• Server URL: The MCP endpoint for the BoldDesk account
• Authentication header: x-api-key
• Header value: The active BoldDesk API key

Validate the MCP Connection

After configuring the client, use a read-only request to verify the connection before performing actions that create or modify BoldDesk data.

Confirm that:

• The client connects to the correct BoldDesk MCP endpoint.
• The BoldDesk MCP tools are available.
• The request returns only data accessible to the API key owner.
• The expected brands and resources are available.
• No authentication or permission error is returned.

After validating read access, test create or update operations only when required.

Troubleshooting

The MCP Client Returns an Authentication Error

Check the following:

• Model Context Protocol is enabled.
• API Key Authentication is enabled.
• The API key was copied correctly.
• The client sends the API key using the x-api-key header.
• The API key is enabled and has not been revoked.
• The MCP endpoint matches the BoldDesk account subdomain or configured custom domain.
• The API key does not contain unintended spaces or characters.

The Connection Succeeds, but an Operation Is Denied

Confirm that the agent who generated the API key has:

• Access to the relevant brand
• Access to the required resource
• The permission required to perform the operation
• A licensed BoldDesk agent account

Also confirm that the requested operation is available through a BoldDesk MCP tool.

The Client Can Access Only Some Brands

The MCP Server applies the accessible-brand scope of the agent who generated the API key. The client cannot use the API key to access brands that are unavailable to that agent.

The API Key Works in One Client but Not Another

Review the configuration requirements for the affected client. Confirm that:

• The MCP endpoint is correct.
• The API key header is configured correctly.
• The client supports remote MCP connections.
• The client supports custom authentication headers.
• The API key is being loaded correctly from the environment variable or credential store.

The API Key Has Been Compromised

Immediately disable or revoke the affected API key. Generate a replacement API key, update the trusted MCP client or backend service, and review the agent’s permissions and integration activity.

By using API key authentication, trusted clients and backend services can securely interact with the BoldDesk MCP Server while remaining within the permissions and accessible-brand scope of the licensed agent who generated the API key.

Frequently Asked Questions

1. What is API key authentication in the BoldDesk MCP Server?
   API key authentication allows a trusted MCP-compatible client or backend service to connect to the BoldDesk MCP Server using an API key generated by a licensed BoldDesk agent.

2. When should API key authentication be used?
   Use API key authentication for trusted backend services, scheduled jobs, service-to-service integrations, and internal automation workflows.

3. Can API key authentication be used with user-facing third-party applications?
   API keys are not recommended for user-facing or untrusted third-party applications. Use OAuth 2.0 when user consent and scoped authorization are required.

4. Whose permissions are applied to MCP requests made with an API key?
   BoldDesk applies the roles, permissions, and accessible-brand scope of the agent who generated the API key.

5. Does an API key allow a client to perform every action available in BoldDesk?
   No. The API key owner must have the required permission, and the action must be supported by a tool exposed through the BoldDesk MCP Server.

6. What happens when API key authentication is disabled?
   MCP clients and backend services that rely on API keys can no longer authenticate until API key authentication is enabled again.

7. What happens when an individual API key is disabled?
   The API key temporarily stops working. Other active API keys and supported MCP authentication methods are not affected.

8. What happens when an API key is revoked?
   The API key is permanently invalidated and cannot be restored. A new API key must be generated if the integration must reconnect.

9. Can one API key be shared across multiple integrations?
   Sharing one API key across unrelated integrations is not recommended. Use separately managed credentials where practical to improve security, auditing, rotation, and revocation.

10. How should I test an MCP connection after configuring an API key?
    Begin with a read-only request, such as Show me my open tickets, and verify that the returned information matches the API key owner’s permissions and accessible brands.

Related Articles

1. Generate and Manage API Keys in BoldDesk
2. Using the BoldDesk MCP Server with AI Assistants
3. List of Available MCP Tools in BoldDesk
4. Overview of BoldDesk MCP Server