Connecting AI Assistants with API Keys

Overview

API Keys let you connect Dashboardly to an AI assistant such as ChatGPT, Claude, or Cursor so the assistant can answer questions about your TikTok Shop data in plain English. You ask "What was my net profit last week?" or "Which SKU sold most yesterday in my UK shop?" and the assistant pulls the answer directly from your live Dashboardly data.

The connection uses an open standard called the Model Context Protocol (MCP), which any modern AI assistant can speak. You generate one API key per assistant (or one per shop), paste it into the assistant's settings, and the conversation is connected to your data.

API Keys are read-only by default. An AI assistant can read the analytics areas listed below, but it cannot create orders, edit settings, send refunds, or modify anything in TikTok Shop. A shop owner or admin can separately create a one-shop key with dated COGS upload permission for a trusted warehouse or ERP integration; that permission is disabled by default and is not exposed as an AI/MCP action. Some specialized Dashboardly pages do not yet have a dedicated MCP tool; the current coverage is stated explicitly below.

You manage all keys on the Settings > API Keys page.

Plan Requirements

API Keys are part of Dashboardly's AI Integrations feature, available on the following plans:

If you are on Brand Starter, the API Keys tab in Settings shows an upgrade prompt. Upgrade your subscription on the Settings > Subscriptions page to enable the feature.

There is no per-key fee. You can create as many keys as you like on an eligible plan, with no extra charge for the queries your AI assistant makes.

How It Works

When you create an API key in Dashboardly, two things happen:

1. The key is generated. It looks like dk_live_... followed by a long random string. You see the full key exactly once, at the moment of creation. After that, Dashboardly stores only a fingerprint of it, so even our support team cannot retrieve the full key later.
2. The key is bound to your account. Each key is tied to your Dashboardly login and, optionally, to a single TikTok Shop. When an AI assistant uses the key to ask for data, it gets back exactly what you would see if you opened that shop in your browser.

Your AI assistant connects to a Dashboardly endpoint (the MCP server) and presents the key. The endpoint verifies the key, looks up which shop the key is allowed to read, and returns the requested data. Every request is logged so you can see how often your assistant is using the key and which questions it asks.

MCP report tools remain read-only. The optional dated COGS permission belongs to the separate Developer REST API and is not available as an AI/MCP action.

Exporting Profitability at Shop, Product, SKU, and Order Level

Your read-only key can retrieve profitability at the level that matches your workflow. Shop totals are available through Dashboard and Profit & Loss data; product and SKU rows are available through Sales & Profit; individual orders can include their complete financial reconciliation. These results use Dashboardly's canonical metric services, including dated COGS, shipping, TikTok fees, manual expenses, ad spend, and preliminary-data indicators.

For an AI assistant, ask for Sales & Profit and specify whether you want one row per product or one row per SKU. Results are paginated, so the assistant can request additional pages until every row has been read. For a server-to-server integration, request GET /api/developer/v1/sales-profit with grain=product or grain=sku. Use the returned pagination details to continue until hasMore is false. The response preserves every profitability field rather than returning only a small fixed set of metrics.

For order-level exports, request orders with financials included. Buyer name, email, phone, address, and tracking details are always excluded, while TikTok Order IDs, Product/SKU IDs, quantities, settlement status, revenue, COGS, shipping, fees, and order profit remain available. This gives warehouse, finance, and reporting systems useful financial data without exposing buyer personal information.

Product Profitability Responses and Filters

The Sales & Profit MCP tool returns the requested product or SKU rows before optional explanatory details, so a large catalog or a detailed data-quality report does not crowd the profitability rows out of the response. Product rows include the complete Dashboardly profitability result, including Ad Spend, Referral Fee, Customer-paid Shipping, Shipping Cost, COGS, Operating Profit, and Net Profit. Ask for one row per SKU when you need variant-level costs and profitability.

By default, the summary and product rows use the same search, Product ID, and SKU filters. The response labels this as summaryScope: "filtered". This means that if you search for one product, the summary describes that product instead of silently showing the whole shop. An integration that intentionally needs shop totals beside filtered product rows can request summaryScope: "whole_shop"; the response labels the different scope explicitly. Filtered summaries use the product-attributed Ad Spend rows, and allocated overhead/manual expenses are applied before Operating Profit and Net Profit are returned, so the visible deductions are not omitted from the profit totals. When TikTok publishes product-level ad revenue without product-level cost, Dashboardly uses the same product-sales allocation as the Sales & Profit cards instead of treating that product's Ad Spend as zero.

Detailed finality notes and the full SKU catalog are optional because they can be much larger than the requested profitability data:

• includeDataQuality: false is the default and returns a compact preliminary versus final summary. Set it to true only when you need the per-metric finality detail.
• includeSkuCatalog: false is the default. Use the SKU breakdown when you need SKU profitability; set this option to true only when you also need every catalog SKU attached to each product.

Ad campaign results come from Dashboardly's imported, shop-specific TikTok Ads data. A response distinguishes between available data, a sync in progress, stale recent data being refreshed, and a date range with no campaign-level attribution. An empty campaign list therefore does not automatically mean your whole-shop Ad Spend is zero; ask for the Marketing Overview total when TikTok does not provide campaign-level rows for the period.

What “Allow dated COGS uploads” Does

The checkbox does not connect Claude, ChatGPT, or another cloud service by itself. It adds a narrowly scoped write:costs permission to the API key you are creating.

When enabled, your own trusted warehouse or ERP backend can send up to 1,000 dated product/SKU costs per request to:

POST https://api.dashboardly.io/api/developer/v1/costs

Each row contains a Dashboardly/TikTok Product ID, an optional SKU ID, a Unit COG, and an inclusive YYYY-MM-DD Effective Date. A product row becomes the product-level default; a SKU row overrides that default for the selected SKU from its Effective Date onward.

The permission is available only when all of these are true:

• the person creating the key is an owner or admin;
• exactly one shop is selected;
• Allow dated COGS uploads is checked.

Existing keys, merchant-wide keys, and default read-only keys cannot write costs. The endpoint updates Dashboardly's dated cost history only; it never writes to TikTok Shop. Keep this dedicated key on your server, not in browser or mobile code.

Step-by-Step: Create Your First API Key

Step 1: Open the API Keys page

Navigate to Settings > API Keys in the left sidebar. If you don't see the tab, check that your subscription is on Brand Growth or higher.

Step 2: Click "New API key"

In the top-right corner of the page, click the + New API key button. A small form opens.

Step 3: Fill in the details

• Name -- A label so you can recognize the key later. Use something descriptive like "Claude Desktop -- US Shop" or "ChatGPT for John". Names are visible only to you.
• Shop -- Choose a single shop, or leave the field on "All shops" to give the key access to every shop you have connected. Most users prefer one key per shop so each AI conversation is automatically scoped to the right data.
• Expires in -- How many days until the key automatically stops working. The default is 365 days. Shorter expiries are safer; longer expiries mean you don't have to rotate the key as often. You can revoke a key at any time regardless of its expiry.
• Allow dated COGS uploads -- Optional and available only to an owner/admin after selecting one shop. Leave this off for AI assistants and reporting integrations. Enable it only for a trusted server-side warehouse/ERP job.

Step 4: Click "Create key"

Dashboardly generates the key and displays it in a confirmation panel. The key is shown in full only this one time.

Step 5: Copy the key immediately

Click the Copy button to put the key on your clipboard. Paste it into a secure place (your assistant's configuration file, a password manager, or a safe note). If you close the panel without copying, you have to revoke the key and create a new one -- there is no way to retrieve it again.

Step 6: Connect your AI assistant

Open your AI assistant's settings and add Dashboardly as a connection (the exact path varies by assistant; see the next section for guidance on each one).

Step 7: Confirm the connection

Ask your assistant a simple question like "What's my net profit for last week?" If everything is set up correctly, the assistant responds with the answer pulled from your live Dashboardly data. If you see an error, see Why isn't my AI assistant working?.

Connecting an AI Assistant

The exact setup depends on which assistant you use. After you create the key in Dashboardly, the confirmation panel shows ready-to-paste configuration snippets for the most popular tools.

Claude (Desktop and Web)

In Claude's settings, look for a section called Connectors, Integrations, or MCP servers. Add a new connection by pasting the Dashboardly endpoint URL and your API key. Once saved, Claude shows Dashboardly as an available connection in any conversation.

If you use Claude Desktop, the connection is added to a configuration file that loads when Claude starts. The confirmation panel in Dashboardly shows the exact text to paste.

ChatGPT

In ChatGPT, open the Apps & Connectors menu and add Dashboardly as a custom connector. Paste the endpoint URL and the API key when prompted. ChatGPT remembers the connection across all your conversations.

Cursor

In Cursor, open Settings > MCP, click Add new MCP server, and paste the Dashboardly endpoint and key. Cursor uses the connection while you code, so you can ask questions like "What's my best-selling SKU this month?" without leaving your editor.

Other AI assistants

Any assistant that speaks the Model Context Protocol can connect. Provide the assistant with the Dashboardly MCP endpoint URL and the API key (treat it like a password). The assistant should automatically discover what data is available.

What Your AI Assistant Can Do

Once connected, your assistant can answer questions across every major area of your shop data. You ask questions in plain English (or any language your assistant supports), and the assistant decides which data to pull.

The assistant cannot perform actions in your TikTok Shop or in Dashboardly. It can only read.

Order results include the TikTok order ID, timestamps, status, fulfillment, line-item SKU identifiers and Dashboardly's canonical signed financial fields. The default is the complete financial response; an integration can explicitly request the lightweight response when it only needs order identity and status. Buyer name, email, phone, postal address and tracking details are never returned.

The full read contracts currently cover Dashboard summary, Sales & Profit, Profit & Loss, Cashflow (when enabled for the shop), Orders, Inventory, read-only Manual Adjustments and Warehouse configuration, customer summary/LTV and aggregate journeys/cohorts, refunds, geographic/hourly order analytics, and the listed Marketing views. Settings, Billing and agency administration do not have dedicated MCP tools because they are account-operational or mutable rather than shop analytics surfaces.

Managing Your Keys

Viewing keys

The Settings > API Keys page lists every key you have created with its name, the first few characters of the key (so you can recognize it), the shop it is bound to, when it was created, when it was last used, and when it expires.

Inspecting usage

Click any active key to expand a usage panel showing:

• Total calls in the last 30 days
• Success rate (calls that returned data successfully)
• Average response time so you know the connection is fast
• A daily activity chart for the last 7 days
• The most-used data tools so you can see what the assistant asks for most

This is useful for confirming that a key is being used, spotting unusual activity, or seeing what your assistant tends to focus on.

Revoking a key

If a key is lost, exposed, or no longer needed, click the Revoke icon next to it. Dashboardly immediately blocks any further requests using that key. AI assistants connected with the revoked key will see an error on their next question.

Revoking is instant. There is no grace period.

Key expiry

Each key has an expiry date set when you create it. Dashboardly shows a warning badge on the API Keys page when a key has 14 days or fewer remaining. Expired keys stop working automatically -- no need to revoke them.

To rotate a key on a recurring schedule, create a new key, update your AI assistant to use it, then revoke the old one.

Connected Apps

Some AI assistants (notably ChatGPT) connect through a one-click sign-in flow instead of requiring you to copy an API key. When you grant Dashboardly access to one of these assistants, it appears in the Connected Apps section at the bottom of the API Keys page.

For each connected app you can see its name, when it first connected, when it was last active, and two ways to disconnect:

• Revoke -- Blocks new sign-ins from that assistant. Active sessions remain valid for up to one hour and then expire.
• Sign out now -- Hard-disconnects the assistant immediately, kicking out any active session. Use this if you suspect the connection is being misused.

Security & Privacy

API keys are sensitive. Treat each key like a password.

• Never commit a key to a public code repository. If you accidentally do, revoke it from Dashboardly and generate a new one.
• Never share a key in a chat message, email, or screenshot. Anyone with the key can read your data until you revoke it.
• Use one key per assistant or per device. That way, if a key is compromised on one device you can revoke just that key without disturbing your other connections.
• Set a sensible expiry. A key that expires in 90 days is safer than one that lasts forever. You can always create a new one.

Dashboardly never displays the full key after creation. The only place to find it is wherever you saved it when the key was generated.

All requests from AI assistants are made over HTTPS. Each request is logged with a timestamp and the data area it queried. You can audit this history per-key from the usage panel described above.

Default keys cannot change product costs, send a refund, or affect TikTok Shop. If you explicitly enable dated COGS uploads, that dedicated key can update Dashboardly costs only for its selected shop. Store it server-side, rotate it regularly, and revoke it immediately if it may have leaked.

Common Questions

Does my AI assistant see my whole Dashboardly account, or just one shop?

It depends on how you configured the key. If you bound the key to a single shop, the assistant only sees that shop. If you left "All shops" selected, the assistant can read data from every shop on your account. Most users prefer one key per shop for clarity.

Can I create different keys for different team members?

Yes. Create one named key per person ("Claude -- Maria", "ChatGPT -- John") and share each key only with the person who needs it. If someone leaves the team, revoke their key without affecting anyone else.

Will using an AI assistant cost me extra?

No. There is no per-query fee from Dashboardly. Your AI assistant provider (OpenAI, Anthropic, etc.) bills you separately for the assistant itself based on their own pricing.

How fresh is the data my assistant sees?

Exactly as fresh as what you see in Dashboardly. If the dashboard shows a metric updated 2 minutes ago, that is what the assistant gets. Settlement-based numbers (fees, taxes) may be estimated for very recent orders -- see Why is my data delayed? for the full story.

Can my AI assistant make changes to my shop?

No. MCP/report access remains read-only, and Dashboardly never writes to your TikTok Shop. Separately, an owner/admin can issue a dedicated, one-shop Developer API key that may upload dated COGS into Dashboardly. Do not give that key to an AI assistant; use it only from your trusted warehouse/ERP backend.

What happens to my old keys if I downgrade my plan?

If you downgrade to Brand Starter, all existing API keys stop working immediately. Re-upgrade to Brand Growth or higher to reactivate them, or create new keys after upgrading.

Can I see what my AI assistant has been asking?

Yes. The usage panel for each key shows the most-used data areas (orders, P&L, top products, etc.) and a 7-day activity chart. We do not log the natural-language questions the user typed -- only which data tools the assistant called.