Create and use an API key

Create and store an API key

Open Account → AI Builder → API Keys, create a named key, and choose an expiry when appropriate. An account can have at most five active API keys. Revoke an older key before creating another when the limit is reached.

The complete key is shown only once. Store it in a secret manager or protected server environment and do not put it in source code, browser code, URLs, screenshots, tickets, logs, or chat messages. Account-created keys currently receive the wildcard scope, which grants the complete API v1 surface for forms and orders the account is allowed to access. The Account key screen does not offer a narrower scope selector.

Use OAuth instead of a static key for a supported connected app when possible. OAuth connections and static API keys are separate credentials and are revoked in different Account sections.

Make a request

API v1 uses the base URL https://ezformz.net/api/v1. Send the key as an HTTP Bearer credential and use JSON for documented request bodies. The interactive API documentation and the OpenAPI document at /openapi.json are the current endpoint references.

The REST API limit is 60 requests per minute per key. Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; honor Retry-After after a 429 response, paginate list endpoints, and record the response request ID for troubleshooting without recording the credential.

Start with a read request and confirm the expected account and form access. New forms are created as drafts; publishing is a separate action.

GET /api/v1/ is a public, self-documenting reference response. It lists the current endpoint families, form-block reference, theme properties, product structure, and example payloads. Use it, /openapi.json, and the interactive docs instead of copying an old endpoint list into an integration.

Common routes include:

• GET|POST /api/v1/forms to list or create forms;
• GET|PUT|PATCH|DELETE /api/v1/forms/{id} for form detail and changes;
• POST /api/v1/forms/{id}/products to add a product to a specific form;
• POST /api/v1/forms/{id}/publish and /unpublish for public status;
• product, option, shipping, coupon, automatic-sale, theme, and image routes listed by the reference;
• GET /api/v1/orders or /forms/{id}/orders, plus GET|PATCH /api/v1/orders/{id}; and
• account and per-form analytics reads.

Both PUT and PATCH on a form are partial updates: send only fields to change. By contrast, an options array on a product update replaces the full option list and must be treated as destructive.

Understand access and returned data

A wildcard key can reach read, write, publish, order-management, analytics, image, theme, and delete operations, but it does not bypass the account's ownership or collaborator permissions.

Under current permissions:

• form-view access can return complete form configuration, payment instructions or destinations, confirmation and redirect settings, Google Sheet URLs, products, variants, and unit costs;
• order-view access can return buyer names and emails, addresses, submitted answers, payment-evidence references, seller notes, totals, status, and tracking data; and
• the raw form password is not returned by the form-detail endpoint; only a boolean indicating whether one exists is returned.

Treat every response according to its most sensitive field. Do not assume that a collaborator-facing integration hides cost or note fields merely because the dashboard labels some of them private. Saved shipping or tax provider API keys, login codes, 2FA secrets, passkeys, and sessions are not part of the supported API v1 response surface.

Make writes cautiously

• Fetch the current resource and review its access metadata before changing it.
• Send only fields you intend to change on partial-update endpoints.
• Treat full option-array replacement and delete operations as destructive. Confirm the exact form, product, option, or order identifier before sending them.
• Inspect the returned object or perform a follow-up read before reporting success.
• Keep separately named keys for different jobs and set expiries for temporary automation. Naming one key “test” does not create an isolated test environment: a key sent to https://ezformz.net/api/v1 is still a live wildcard production credential.
• Avoid sending buyer data to logs or another processor unless it is required and appropriately protected.

When changing a shared form, the API enforces the signed-in account's collaborator permissions. Owner-only Google Sheets fields remain owner-only. Forms using shared inventory reject stock and low-stock writes through ordinary form product endpoints; make those changes from the Inventory workflow.

Use server-returned request IDs in diagnostics. A 404 can intentionally hide a form or order the key is not allowed to access, while 403 identifies a recognized operation that lacks permission. On 409, reload the current resource and resolve the concurrent change instead of blindly replaying stale input.

Revoke and respond to exposure

Revoke a static key from Account → AI Builder → API Keys. Revocation blocks future EZFormz authentication with that key, but it cannot erase data already copied to logs, caches, databases, AI chats, or another service.

If a key may have been exposed, revoke it first, create a replacement only for the systems that still need access, update those systems, and remove the old value from their storage and logs. Review the key's last-used information and affected form or order state without sharing the credential in a support ticket.