AdAce AdsAdAce Ads API keys: scopes, expiry, verification and revocation
An AdAce Ads API key authenticates a supported MCP client or REST integration without an interactive sign-in on every request. It is a credential, not a Google or Meta token. Create one only for a specific integration and workspace, start with the minimum scope, and check what the integration can actually read.
What a key authorizes
A key is bound to its workspace and user. Its effective permissions are the intersection of the key's scopes and the user's current role, with client access checked by the application. A role change can therefore reduce what an existing key may do. Copying a workspace identifier into a request does not grant access to that workspace. Use read for reporting; a key cannot independently grant access to an unassigned client or disconnected provider account.
The full ak_prefix_secret value is returned once at creation, while AdAce Ads stores a hash for verification. The displayed prefix identifies a key without revealing its complete value. Save the full credential in the receiving integration's approved secret configuration. Do not put it in an ordinary AI message, a URL, source code, screenshots or troubleshooting logs. A missing saved value cannot be recovered from the prefix: create a replacement and revoke the lost key.
Through REST, keys permit reads and, with propose scope, creation of change proposals; they do not directly permit approval, execution or settings changes. However a proposal is not inherently inert: a client's configured auto policy may progress an eligible proposal within the applicable permissions and limits. MCP also applies scope and role checks to its available tools. Use read for a reporting rehearsal instead of assuming propose guarantees human review of every subsequent action.
For example, create a read key named 'North Store weekly report' with an expiry appropriate to the review period. Configure the supported client to send it as an Authorization Bearer credential to the documented endpoint. Call get_started through MCP, then read the permitted client's account list. Compare one recognizable account with the application. This proves a useful read path without creating proposals or changing advertising.
Credentials with a clear owner and purpose
- Give each trusted integration a recognizable credential so ownership and purpose remain clear when reviewing access later.
- Limit access with scope, current user permissions and workspace binding rather than sharing an agency password or provider token.
- Replace one integration's credential when needed and verify the replacement before removing the obsolete credential during routine rotation.
Create, verify and rotate
- Open Connect AI → API keys in the intended workspace. Review the existing names, active count and last-used timestamps before creating another credential.
- Create a named key with read for the first verification. Select an expiry where appropriate and complete any second-factor requirement enforced by the application.
- Save the one-time value directly in the trusted integration's secret configuration. Keep only its name, prefix, owner, purpose and expiry in your access inventory.
- Use the integration to make a permitted read. Check both the returned data and the relevant activity or last-use evidence; the key's last-use timestamp is updated at most once per minute.
- For routine rotation, create and verify the replacement, switch the integration and revoke the old key. If a key is exposed, revoke it promptly and investigate its activity before setting up a replacement.
Limits, errors and exposed credentials
- Creation limit: the implementation permits five active keys per person in a workspace. Expired or revoked keys no longer occupy an active slot. Review obsolete integrations instead of sharing a key to avoid the limit.
- 401 or rejected credential: check the endpoint, Bearer header, complete value, expiry and revocation. 403: check workspace, effective scope, current role and client assignment. A read key should not be widened merely because a settings or proposal request was refused.
- A rate-limit response requires waiting according to Retry-After and reducing repeated calls; it does not mean the key was revoked. Key revocation blocks subsequent authentication but does not remove previous reports or undo changes. Local tests verify implementation rules, not production integration acceptance or public paid availability.
Sources and further reading
Try it on your own accounts
Create a workspace, connect Google or Meta in a couple of clicks and see your accounts clearly. Changes follow your approvals or the policy you configure.
Create your workspace