Skip to main content
API keys authenticate requests to the Mavel REST API. Pass the key in an X-API-Key HTTP header on every request (a query-string fallback exists, but never use it; see Security practices below). Keys are project-scoped: each key is tied to a specific project (or to the organization, with access to any of its projects) and cannot reach data outside that scope.
API access requires the Growth plan or above. On Starter and Pro, the API Keys page shows an upgrade prompt. See Plans and billing.

​
Provisioning a key

Self-serve key creation in the dashboard is coming soon. In the meantime, contact support@newbest.ai to provision an API key for your organization. If you are on Growth or Enterprise, you can also connect through the MCP server today without waiting for a key. Once provisioned, you will receive the key value once: copy it immediately and store it securely. Mavel stores only a hashed fingerprint; the raw key is not recoverable after the creation response.

​
Using a key

Pass the key in every API request using the X-API-Key header:
Include the project_id query parameter (for GET endpoints) or in the request body (for POST endpoints) to scope the request to the right project. The API returns a 403 if the key’s bound project does not match the requested project_id.

​
Rate limits

The API enforces a limit of 200 requests per minute per project. Each response includes rate-limit headers so you can track remaining headroom: When the limit is exceeded, the API returns 429 Too Many Requests. Back off and retry after the X-RateLimit-Reset time.

​
Revoking a key

Contact support@newbest.ai to revoke a key. Revoked keys are immediately rejected by the API. If a key may have been exposed, request revocation right away. Do not wait.

​
Security practices

  • Never put keys in URLs. Query-string parameters appear in server logs, browser history, and referrer headers. Always use the X-API-Key header.
  • Never commit keys to source control. Store them in environment variables or a secrets manager.
  • Never expose keys in client-side code. All API calls must originate from your server or a trusted backend process, not from browser JavaScript.
  • Rotate promptly if a key leaks. Request a revocation and a new key from support as soon as you suspect exposure.

​
MCP as an alternative

If you need AI tools like Claude or Cursor to query your Mavel data, the MCP server is often simpler than raw API calls: it exposes your visibility data as structured tools that AI clients can call directly, without you writing API integration code. MCP access requires the same Growth plan gate as the REST API.