Tencent Ads Authentication

Problem Statement and Goal

When interacting with the Tencent Ads API (api.e.qq.com) for tasks like data retrieval, ad campaign management, or analytics, the first mandatory step is authentication. This involves obtaining, storing, and using the sensitive X-MKT-API-Key credential. Managing this API key directly presents several specific challenges:

• Security Risks: The key should never be exposed in plaintext within dialogues or logs to prevent accidental leakage.
• Cumbersome Configuration: Manually setting the key in code or configuration files is error-prone and complicates sharing it across different tools or skills.
• Opaque Status: There is no quick way to check if the current authentication is valid, hindering efficient error diagnosis.

The tencentads-auth skill provides a standardized, conversational workflow to guide users through securely and efficiently configuring Tencent Ads API authentication. It establishes a unified authentication foundation for all subsequent tencentads-* series skills.

How the Skill Works

The core function of this skill is secure credential storage and automated status checking. It does not execute ad business logic but focuses exclusively on managing the authentication lifecycle.

Core Capabilities and Key Steps

1. Pre-check for Authentication Status: Before initiating any authentication flow, the skill automatically runs the auth-status.mjs script. This script reads locally stored credentials and verifies their validity. If the returned status is "active", the credentials are confirmed to be valid, and no user action is required.

2. Conversational Key Configuration: When configuration or an update is needed, the Agent guides the user to send their API Key (formatted as a string starting with mkt_) in the dialogue. Upon receiving it, the Agent never echoes or repeats this key in the reply. Instead, it immediately invokes the auth-save-apikey.mjs script to securely store the credential.

3. Centralized Credential Management: All tencentads-* skills share a unified storage mechanism. The saved API Key is automatically read by the internal callApi function in any subsequent skill that needs to call the Tencent Ads API (e.g., campaign management, reporting skills), achieving "configure once, use everywhere."

4. Handling Authentication Failures: When another skill (e.g., tencentads-query) encounters an authentication error while calling the API (e.g., AUTH_REQUIRED or AUTH_EXPIRED), it references this skill. The skill then guides the user to provide and save a new key, and automatically retries the original operation that triggered the error.

Script Invocation Standards

• All scripts must be executed from the skill's root directory.
• Parameters are passed using explicit command-line arguments (e.g., --api-key) instead of JSON strings to ensure cross-operational system compatibility.
• The credential-saving script auth-save-apikey.mjs is a sensitive operation and must be invoked directly by the Agent to avoid credential exposure through other channels.

Usage Boundaries and Important Notes

• Prerequisite: The CLI tool must first be installed via npm install tencentads-cli@1.0.0, and the environment requires Node.js version 20 or higher.
• Skill Positioning: This skill is a foundational service component. It does not provide direct ad data querying or management capabilities. Its sole purpose is to manage authentication; all ad operation capabilities are provided by other tencentads-* skills.
• Security Principle Reiterated: Under no circumstances should the API Key be echoed, logged, or stored in any insecure location within dialogues. The Agent's role is to act as a secure intermediary for obtaining and persisting the key.
• Credential Storage: Credentials are stored on the local file system. In shared environments or multi-user scenarios, access permissions for the file system must be configured properly to prevent unauthorized access to credentials.
• Applicability Scope: This skill is designed exclusively for scenarios where the tencentads-cli and its associated skills are used to call the Tencent Ads API. It is not intended for use with other cloud services or integrations not based on this CLI framework.