Scoped API keys.
Every request is authenticated with an organization API key that carries explicit scopes. One key works for REST and MCP; grant only the scopes a workload needs.
dc_live_<prefix>_<secret>
The prefix identifies the key in your dashboard and logs. The secret is shown once when the key is created; Data.co stores only the prefix and a SHA-256 hash of the secret and cannot show it again.
Send the key as a bearer token: Authorization: Bearer dc_live_… . Keys belong to an organization, not a person, so they survive staff changes. Revoke a key at any time from app.data.co.
The organization is always taken from the verified key, never from anything in the request. A key is rejected if it is malformed, unknown, revoked or expired, or if its organization is suspended. The organization must also have the marketplace module enabled; otherwise requests fail with not_entitled.
What each scope allows
| Scope | Allows |
|---|---|
| datasets:read | Catalog metadata: datasets, schemas, providers |
| datasets:query | Record search within a dataset, and bulk download grants |
| legal:read | The legal endpoints backed by the LAW.co connector |
| mcp:invoke | Calling the MCP server — needed in addition to each tool's resource scope |
| usage:read | This organization's own metering events |
| control:read | Read Control resources and use Control gateways |
| control:write | Modify Control resources |
| admin | Every scope |
What happens to every request, in order
REST and MCP share one pipeline, so a request fails at the first check it does not pass.
- 1
Authenticate
The key is verified. Failure returns 401 invalid_api_key with a WWW-Authenticate header.
- 2
Load entitlements
Your plan, modules and any overrides are loaded. A missing module returns 403 not_entitled.
- 3
Rate limit
One token is taken from the key's per-minute bucket. An empty bucket returns 429 rate_limited with Retry-After.
- 4
Check scope
The operation's scope must be on the key. Otherwise 403 missing_scope, with param naming the scope.
- 5
Validate and meter
Inputs are validated (400), the monthly quota is checked (429 quota_exceeded), then rights and dataset tier (403), before the provider is called.
Authentication failures
{
"data": null,
"meta": { "request_id": "req_…", "api_version": "v1", "demo": false },
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked.",
"param": null,
"request_id": "req_…"
}
}Illustrative example · final API surface documented in /docs
Suggested scopes per workload
| Workload | Scopes |
|---|---|
| Catalog browser or dataset picker | datasets:read |
| Backend legal search | legal:read |
| Pipeline over one dataset | datasets:read, datasets:query |
| AI agent over MCP | mcp:invoke, legal:read, datasets:read |
| Usage dashboard or cost alerting | usage:read |
Key hygiene
- One key per workload
- Least-privilege scopes
- Keep keys server-side, never in browsers or mobile apps
- Rotate on staff or vendor changes
- Revoke unused keys
- Watch usage:read for anomalies
- Never paste keys into prompts or agent memory
Keys, agents and Data.co Control
An API key identifies an organization and a set of scopes, not the person or agent using it. For most integrations that is enough. When you need to know which agent made a request and on whose behalf — and apply purpose, approval or user-level policies — route traffic through Data.co Control, where agents get identity tokens of their own and can act on behalf of named users.
Keep keys out of model context. An agent that can read its own key can leak it in output. Store keys in your secret manager, inject them into the MCP client configuration or your backend, and give each agent deployment its own key so it can be revoked without affecting others.
Questions buyers ask
Do you support OAuth?
Not today. Organization API keys are the only method. OAuth for user-delegated access may follow.
Can I restrict a key to one dataset?
Scopes are per capability today, not per dataset. Dataset-level restrictions are planned through Data.co Control policies.
How do I rotate a key without downtime?
Create a new key with the same scopes, deploy it, confirm traffic has moved using the usage events, then revoke the old key.
Does a revoked key stop working immediately?
Yes. Verification happens on every request against the stored key record, so a revoked key fails with invalid_api_key on its next call.
Are denied requests logged?
Permission and rights denials are written to your organization's audit log as api.rest.denied or api.mcp.denied, with the request id.
Where do I create keys?
In app.data.co › Marketplace › API Keys, or Administration › API Credentials. Sign up at app.data.co and create one now.
Can one key serve several environments?
It can, but separate keys for development, staging and production make revocation and usage tracking much simpler.
Are keys shown again after creation?
No. Only the prefix and a hash of the secret are stored. If a secret is lost, create a new key and revoke the old one.
API and MCP access is live.
Sign up at app.data.co, create an organization and issue a scoped key for REST and MCP.