API Keys

Create and manage API keys in the dashboard to authenticate with the v1 API, the SDK, the CLI, and the MCP server.

Where to manage keysCopy Anchor Link

In the app, go to Settings, Developer console, Keys. From there you can:

• Create a key with + Create API key. You choose its Name, Project, Environment, and Scopes.
• See each key's prefix, project, scopes, last use, and status.
• Rotate a key: a new secret is issued, and the old one keeps working for a grace period you set in hours (24 by default, 0 to stop it immediately).
• Revoke a key. A revoked key stops authenticating at once.

Key formatCopy Anchor Link

Keys carry their environment in the prefix:

• ace_live_... runs against your account for real and draws on your credit balance.
• ace_test_... is free and capped by a monthly quota, which makes it the right choice for a first integration.

The full key is shown only once, at creation or rotation. Store it securely. The dashboard shows only the prefix afterwards, for identification.

ScopesCopy Anchor Link

A key carries one or more scopes. admin grants all of the others.

A write scope also satisfies the matching read check, so a key with enrichment:write can read jobs and a key with feeds:write can download an export. The utility endpoints accept utils:read, enrichment:read, or enrichment:write.

New keys get enrichment:read, enrichment:write, and utils:read by default. That covers the enrichment engine and the utilities. Webhooks, ratings, and feeds each need their own scope.

ratings:read and ratings:write are never granted by default. Review text carries a public display name, so sending it is personal-data processing and has to be an explicit choice rather than something a key picks up automatically.

feeds:read and feeds:write are separate from the enrichment scopes so that a key which moves catalogue data cannot also spend credits or control jobs.

Creating, renaming, and deleting a project needs admin. There is no narrower scope for it, because those change what the account is made of rather than what is in one project.

The Scopes list in the Create API key dialog offers every scope in the table. You can also name them yourself with POST /api/keys.

Scopes are enforced on the MCP server too. A tool whose scope your key lacks is refused with a message naming the scopes it needs, so use a wider key rather than retrying. See the API Reference for the scope each endpoint checks.

Project scopeCopy Anchor Link

A key is either pinned to a project or account-wide. You choose in the Project field when you create the key: pick a project, or pick Account-wide (every project). A key's project cannot be changed later. Rotating a key keeps its project.

• Pinned: the key defaults to its own project, so you can omit projectId. Naming a different project returns 403 PROJECT_SCOPE_MISMATCH.
• Account-wide: the key can reach any project on the account, but endpoints that return project-scoped rows require you to say which one. Omitting projectId returns 400 PROJECT_ID_REQUIRED:

{
  "error": {
    "code": "PROJECT_ID_REQUIRED",
    "message": "This endpoint returns project-scoped data. Pass ?projectId=<id>, or use a key pinned to a project."
  }
}

This applies to GET /feeds, GET /feeds/{id}, and POST /feeds (which takes projectId in the body). GET /feeds and GET /feeds/{id} previously merged rows from every project on the account when no project was named, with nothing in the response to say which project each row came from, so there was no safe way to read the result.

Either name the project:

curl "https://ace.authoritas.com/api/v1/feeds?projectId=<id>" \
  -H "Authorization: Bearer $ACE_API_KEY"

or create a key pinned to a project under Settings, Developer console, Keys and drop the parameter entirely.

The feed source, delivery, export, and enrichment endpoints address a feed by id, so they need no projectId. A pinned key that addresses a feed in another project still gets 403 PROJECT_SCOPE_MISMATCH. The ratings endpoints also need a project: pass projectId, or use a pinned key.

Project ids come from GET /projects. See Error codes for the full list.

Environments and quotasCopy Anchor Link

An ace_test_ key is free and metered against a monthly ceiling: 1,000 requests and 500 units of work per calendar month, shared by every test key on the account. When either is exhausted, calls return 402 TEST_QUOTA_EXCEEDED until the month rolls over. Check what is left with GET /api/v1/usage, which includes a testQuota block for test keys. Only requests that do metered work count against the quota, so reads and the utilities stay free.

An ace_live_ key draws on your credit balance instead. See Credits and usage.

Rate limitsCopy Anchor Link

Each key has a requests per minute limit, counted in fixed one-minute windows. A live key gets 120 requests per minute unless a different limit was set when it was created. A test key is capped at 20 per minute whatever its stored limit.

Every authenticated v1 response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix timestamp). When the limit is exceeded, the API returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header in seconds.

The console does not have a field for the limit. Set it with rate_limit_per_minute when you create the key through POST /api/keys, or change it later with PATCH /api/keys/[id].

REST management (session auth)Copy Anchor Link

These routes manage keys for the signed-in user. They use session (cookie) auth, not an API key, so call them from a page or script that shares your browser session.

POST /api/keys accepts:

For example, a key that can only move feed data for one project, created from the browser console while signed in:

const res = await fetch("/api/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "PIM sync",
    env: "live",
    scopes: ["feeds:read", "feeds:write"],
    project_id: "<project-id>",
  }),
});
const { data } = await res.json();
console.log(data.key); // shown once

See alsoCopy Anchor Link

• API Reference: full v1 overview, scopes, jobs, and errors
• Feeds API: the endpoints the feeds:* scopes unlock
• MCP Server: connect an AI assistant with the same key
• Getting Started: your first call, end to end