Authentication & keys

Every REST request and every MCP tool call is made on behalf of one workspace, with either an API key or an OAuth token. This page explains keys, modes, scopes and team roles, and how to keep keys safe.

#Send your key

Send the key as a Bearer token on every request:

Authorization: Bearer au_test_...

X-Api-Key: au_test_... is also accepted, but prefer the Authorization header: it is what MCP clients and most HTTP tooling expect. Keys are never accepted in a URL or query string.

Keys have a fixed format: au_test_ or au_live_ followed by 43 URL-safe characters. A value that does not match this format is rejected with 401 invalid_api_key before any lookup, so a key with extra spaces, quotes or a line break fails immediately. Check the configured secret first when you see that error.

Check a key at any time with the free account endpoint:

curl https://data-services.autouncle.com/v1/account \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY"

require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/account")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))

import json
import os

import requests

response = requests.get(
    "https://data-services.autouncle.com/v1/account",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data-services.autouncle.com/v1/account", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
  },
});
console.log(JSON.stringify(await response.json(), null, 2));

#Test and live modes

Both modes use the same endpoints, validation, scopes, per-minute rate limits and error codes, so code that works with a test key works with a live key. Swap the secret, not the code. Test keys also have the fair-use allowance above, so a test key is not a free production resolver. See testing with test keys and limits.

#Scopes

A key has one or more scopes. A call without the right scope fails with 403 insufficient_scope.

New keys get all five scopes unless you clear some. Give production keys only what they use: a backend that values listings needs valuations:write and probably catalogue:read; a reporting job that reads results back needs only valuations:read.

#Create a key

Open API keys in the console. Owners, admins and developers can create keys. The options are:

The full secret is shown once, right after you create the key. Copy it straight into your secret manager. The console afterwards shows only the key's name, prefix and last four characters.

#Countries: workspace and key

Two lists decide which markets a key may value:

1. The workspace's markets. New workspaces can value every publicly available market. AutoUncle can narrow this for your workspace.
2. The key's allowed countries, if you set any.

A market must pass both. Otherwise the valuation is rejected with 403 country_not_enabled before anything is recorded or charged. GET /v1/account shows what passes both for the calling key in allowed_countries, as the ISO codes you send in country. A key's own restriction is also visible on the API keys page.

#Revoke a key

Choose Revoke next to the key on the API keys page. Revocation is immediate: the next request with that key returns 401 key_revoked. Revoked keys stay listed so their usage history remains readable. Developers can revoke the keys they created; owners and admins can revoke any key.

Rotate keys by creating the new key, deploying it, checking traffic in Request logs, then revoking the old key.

#Team roles

A workspace has members with one of four roles. Invite people under Settings.

A workspace always keeps at least one owner or admin: the console refuses a role change or removal that would leave nobody in charge.

#Invitations

• An owner or admin invites a colleague by email with the role admin, developer or viewer.
• The invitation link is valid for seven days.
• It can be accepted only by a signed-in user whose verified email matches the invited address. Otherwise it fails with email_verification_required.
• Resend issues a fresh link and invalidates the previous one. Each invitation can be resent up to three times an hour.
• An expired, used or revoked link shows invalid_invitation. Ask an owner or admin to send it again.

#Agents and OAuth

MCP clients can connect with an API key header or by signing in with OAuth. An OAuth token is bound to the Data MCP endpoint and to the workspace you choose during consent, and your membership and scopes are checked again on every tool call. OAuth valuations are live and use credits. OAuth or API key explains how to choose.

#Key hygiene

• Keep keys on the server. Never ship a key in a browser app, a mobile app, a public repository or a shared notebook.
• Never put a key in an agent prompt or in a file an agent may print. Configure it as an environment variable or through the client's secret store.
• Use one key per service and environment, with only the scopes and countries it needs and, for live keys, a monthly credit limit.
• Never log the Authorization header or the full key. Log the key ID (key_…) from GET /v1/account, or the request ID from each response, instead.
• Rotate keys when people leave the team or a key may have been exposed, and revoke the old key.
• Set an expiry on keys for trials, demos and contractors.