Understand the authentication options available for Webex Connect APIs and Webhooks
Authentication options for Webex Connect APIs and Webhooks
All requests to the Webex Connect APIs and Webhooks are authenticated using either a key or JSON Web Tokens (JWT). Here are the authentication details for various APIs offered by Webex Connect.
Note
If you are looking for Authentication details for Webex Connect Sandbox APIs, please refer to Sandbox APIs Overview.
| API / Webhooks | Authentication Types Supported |
|---|---|
| Messaging API (v1 and v2) | 1. Service Key 2. Service Specific JWT Tokens (Refer to know how you can access Service Keys and Jason Web Tokens for a Service in Webex Connect). |
| Custom Event API v1 | 1. Service Key 2. Service Specific JWT Tokens |
| Inbound Webhooks | 1. Service Key 2. Service Specific JWT Tokens |
| Contact Policy APIs | Profile Key (Available under Tenant Settings page. Refer to Profile Key for more info.) |
| RCS Capability Lookup API | 1. Service Key 2. Service Specific JWT Tokens |
| Profile API v2 | Profile Key (Available under Tenant Settings page) |
| Thread APIs | JWT Tokens (Refer JWT Set-up Tutorial in SDK Docs) |
| Segment APIs | JWT Tokens (Refer JWT Set-up Tutorial in SDK Docs) |
| Topic APIs | JWT Tokens (Refer JWT Set-up Tutorial in SDK Docs) |
| User Audit Logs API | Cisco Webex Common Identity (CI) (Refer Webex Contact Center Authentication) |
Authentication Best Practice
You can use either Service Key or JSON Web Tokens (JWT) for authentication when using Messaging APIs, Custom Event API v1, inbound webhooks, and other APIs mentioned above. If you use both JWT authentication and Service Key in an API request, JWT authentication takes priority, and the Service Key is ignored.
Authentication for MCP messaging tools
MCP messaging tools use an OAuth 2.0 access token generated from the Integration App credentials configured in the MCP client. The Integration App must include the spark:mcp scope. The MCP client uses this token to authenticate requests to the Webex MCP Server.
The access token identifies the user and organization context for the AI agent request. Webex Connect uses this context to validate the tenant and process SMS and email messages through the default AI service created for MCP Messaging for AI Agents.
When calling MCP messaging tools:
- Configure the MCP client with the OAuth 2.0 details for the Integration App.
- Generate an access token with the
spark:mcpscope. - Send the generated access token in the
Authorizationheader. - Ensure that MCP Messaging for AI Agents is enabled for the tenant.
- Ensure that the SMS phone number, alphanumeric Sender ID, or email app asset is enabled for AI Agent Messaging and mapped to the selected use case.
MCP messaging authentication is separate from the Service Key and JWT authentication methods used for direct Messaging API calls.
Rotating API Authentication Credentials
We encourage you to rotate your API credentials (Service Key and/or JWT tokens) periodically to strengthen your security posture and prevent unauthorised access. Refer to Rotating authentication credentials periodically to understand how you can create a new Service Key / JWT credentials and discard existing ones as per security best practices.
IP Allowlisting for APIs and Webhooks
Additionally, Webex Connect supports IP Address Allowlisting to validate the request source for supported APIs and inbound webhooks. Tenant Owners can add valid IPv4 addresses or CIDR ranges from Tenant Settings.
When IP addresses or CIDR ranges are configured, API traffic for the tenant is restricted to those entries only. Requests that do not originate from the configured entries are rejected.