Skip to main content

Authentication

The public HTTP API and remote MCP endpoint authenticate requests with a urlquery API key.

Get an API key​

  1. Create an account. On urlquery.net, choose Create an account on the sign-in page and register with an email address and a password of at least 8 characters. New accounts start on the free plan.
  2. Verify your email address. Follow the link in the verification email. API keys can only be created after the address is verified.
  3. Create a key. Open Settings → API keys and choose New API key. Give the key a name of 3 to 80 characters that says where it will be used, for example siem-enrichment, and optionally a description.
  4. Copy the key now. The page shows the key once. Store it in a secrets manager or environment variable; afterwards the list shows only its name, status, and creation date.

You can create several keys and delete any of them with Delete. Deleting a key immediately breaks every application that uses it, and it cannot be undone. Create one key per application so you can revoke one without affecting the others.

If your account belongs to a team, the keys you create belong to the team: every team member can see and delete them. Requests made with a key act as the member who created it. See plans and features.

Sign in with Google works only for an existing account with the same verified email address; it does not create a new account.

HTTP API​

Send the key in the x-apikey request header:

curl --fail-with-body \
  --header "x-apikey: ${URLQUERY_API_KEY}" \
  "https://api.urlquery.net/public/v2/reports/recent?limit=1"

Header names are case-insensitive, but the documentation consistently uses x-apikey. In the HTTP API, a missing key returns 401 MISSING_API_KEY, and an invalid or disabled key returns 403 INVALID_API_KEY. The MCP endpoint rejects a request without a key with 401.

MCP​

Configure the MCP client to add the same header to requests sent to https://mcp.urlquery.net/mcp. The key belongs to the client process and is passed through to urlquery for each tool call. The MCP server does not use one shared credential for all users.

See Connect an MCP client for configuration examples for Claude Code, Codex, VS Code, Cursor, Claude Desktop, and opencode.

Handling API keys​

  • Store keys in an environment variable or a secrets manager.
  • Never put a real key in documentation, source code, issue reports, or chat transcripts.
  • Avoid command forms that place the key directly in shell history.
  • Use a dedicated account for automation so its key can be rotated without affecting people.
  • Rotate a key immediately if it may have been exposed.

Authentication does not guarantee access to every report or operation. Report visibility, account permissions, team membership, and quotas are evaluated separately.