clay v2.0.0

The pack names a reference, never a secret. Installing a pack registers capabilities and makes them governable; registration is not connectivity. The credential is created at the provider and held in the client's own secret manager under the reference the pack names, and deployment testing is still required to show the credential path works and cannot be bypassed.

Reference

secret-ref-clay-api-key

Custody

customer_vault

Injection

header (clay-api-key)

A Clay Public API key, held in the client's own secret manager. The stored material must be the complete clay-api-key header value: the bare key with no scheme prefix, as Clay's own examples send it. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only. Issuance, per Clay's quickstart: a key is created in the Clay app under Settings > Account > API keys (currently labeled beta), or generated by the agent plugin after install. Scope model: Clay documents keys as tied to a specific Clay user and inheriting that user's workspace access — a key is not a service account, so it can reach exactly what its creating user can reach, and it stops working if that user is removed from the workspace; mint the key from a user whose workspace membership is limited to what this integration needs, monitor for 401s, and tie key rotation to the offboarding process, because there is no org-scoped alternative today. Least privilege: the key inherits the user's workspace access wholesale (no per-endpoint scoping is documented), so least privilege is exercised through the choice of the issuing user, and through the deployment's own spend ceiling — Clay documents credit budgets only for MCP users, not for Public API keys. Expiry and revocation: the retrieved first-party pages document creation but not scheduled expiry, rotation semantics or a revocation API (the dedicated authentication page could not be retrieved this session); treat keys as long-lived until deleted in Clay settings, own rotation and revocation as external administrative actions, and ensure a stale value fails closed. The executor injects the stored value verbatim and performs no credential lifecycle itself. Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

• clay-gtm-database (api, pii): https://clay-public-api.invalid/public/v0/search/query-mode
• clay-routine-runs (api, pii): https://clay-public-api.invalid/public/v0/routines
• clay-tables (api, pii): https://clay-public-api.invalid/public/v0/tables/query

The endpoint host 'clay-public-api.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD, a deliberate fail-closed default): substitute the real host before enabling, in the endpoints, the resource locators and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step. The real host is api.clay.com and every registered path sits under the /public/v0 base path of Clay's Public API, the developer platform Clay launched on 9 July 2026. This pack registers only operations documented in Clay's official developer documentation at developers.clay.com, retrieved on the review date: the search query-language reference read, advanced-search create and run, routine run start, routine run results read, and the table query. Searches are POST-with-query-body shapes whose documented effect is retrieval: creating a search posts a query in Clay's documented query language and returns a search_id (no records change hands), and running a search is a stateful iterator that pages records until has_more is false — both are registered read at R0. Searches are plan-capped metered reads: Clay documents per-request, per-search and per-period result limits by plan, and returns HTTP 402 (naming the limit hit) when the search quota is exhausted — 402 means out of budget, not slow-down-and-retry; malformed input returns 400. Routine execution is registered execute at R2 because a run is money-adjacent metering: Clay documents that API and CLI work consumes the same Data Credits (purchased data) and Actions (operations) as equivalent in-product runs, so every run spends the workspace's paid balance; Clay documents no per-key credit budget on the Public API path (budgets exist only on the MCP surface), so the deployment must impose its own spend ceiling. Runs are asynchronous: the run call returns a routine_run_id and results are polled from the results endpoint. Routine ids for custom functions use the documented format function:t_... — ROUTINE_ID and ROUTINE_RUN_ID are placeholders the deployment binds before enabling. Inline runs accept 1 to 100 items; the batch run surface (presigned upload URL plus run-batch start) is not registered by this pack. Workflows are documented as Alpha; this pack registers function routines only. The table query is documented Enterprise-only and read-only: there is no list-tables endpoint, so the integration must already know its table ids (found in the Clay app URL after /tables/), and the table id travels in the request body, not the path. Documented exclusions, framed as what this pack does not register: table writes of any kind (Clay documents the Tables primitive as read-only — no create-table, add-field or write-record operations), the older filters-mode search, batch routine runs, webhook management (run-completion webhooks are created with the clay CLI and verified with X-Clay-Signature), the Audiences and Signals primitives, the MCP surfaces (the hosted MCP connector and the local stdio MCP server that ships with the agent plugin) and the clay CLI itself — those are local or OAuth-gated surfaces outside this pack's HTTP connector — and the in-table HTTP API enrichment column, which is outbound from Clay, not an endpoint a caller invokes. People search results and routine/table outputs conventionally contain prospect names, titles, employers and locations — personal data, registered at the pii class. The review state is draft: the first-party developer documentation was retrieved for this review, but the developers.clay.com/authentication page could not be retrieved this session, and the retrieved pages do not document key expiry, scheduled rotation or a revocation API — those custody properties are unresolved vendor-side (see the credential note).

Draft review record dated 2026-09-21 · Reviewer: aaes-eng (an opaque id that resolves internally to the responsible reviewer)

• https://developers.clay.com/ (retrieved 2026-09-21)
• https://developers.clay.com/quickstart (retrieved 2026-09-21)
• https://developers.clay.com/searches (retrieved 2026-09-21)
• https://developers.clay.com/searches/advanced (retrieved 2026-09-21)
• https://developers.clay.com/routines/api (retrieved 2026-09-21)
• https://developers.clay.com/tables (retrieved 2026-09-21)
• https://www.scalekit.com/blog/clay-mcp-vs-api (retrieved 2026-09-21)

A pack review is not a vendor or examiner attestation. A retrieval date says when a source page was read; it does not by itself establish what the page said then. No pack is vendor-endorsed, and none has been connectivity-tested against a live vendor tenant.