# auth.md

You are an agent that wants to call the Datahyena API on a user's behalf. This file describes how to obtain credentials and how to handle them safely.

Two hosts are relevant:

- **Resource server** — `https://api.datahyena.com` — the API you will call (`/v1` for REST, `/mcp` for MCP).
- **Dashboard** — `https://app.datahyena.com` — where the user manages their account, keys, and MCP connections.

## Current state

Datahyena does not support agentic registration today. REST credentials are issued by the user out of band; MCP uses a browser OAuth flow the user completes themselves. This file tells you how to pick credentials up and use them without putting them at risk.

## Use the existing tooling first

Before you do anything credential-shaped, check whether the user has already wired Datahyena into your environment.

1. **Datahyena MCP server** — if you are an MCP client (Claude, Cursor, Codex, Gemini, or anything that speaks remote MCP over Streamable HTTP), connect to `https://api.datahyena.com/mcp`. Authentication is OAuth 2.1 with PKCE: the user signs in and approves read scopes in the browser, and you call the tools without ever seeing a credential. Discovery: `https://datahyena.com/.well-known/mcp/server-card.json`.
2. **An existing key in the environment** — if `DATAHYENA_API_KEY` is already set, or the project `.env` contains one, use it.

If either of these is available, use it and stop. Do not ask the user for an API key you do not need.

## Supported login option: API key, supplied out of band

The only REST credential is a Datahyena API key (prefix `dh_live_`). The user issues it from the dashboard at `https://app.datahyena.com` and supplies it to you through a secure channel, never by pasting it into chat.

### How to pick the key up

Look for it in this order. Stop at the first one that exists:

1. `DATAHYENA_API_KEY` in your process environment.
2. A project `.env` file the user has told you to read.
3. The MCP connection, if one is configured (in which case prefer the MCP tools over raw REST).

If none of the above is set and you genuinely need a key, **do not ask the user to paste it into the conversation**. Instead, tell them to:

- Create an account at `https://app.datahyena.com/register` if they do not have one (50 free credits, no card required), then create an API key from the dashboard. Keys are shown once at creation.
- Put it in `DATAHYENA_API_KEY` in their shell or `.env`, whichever matches how they invoke you.
- Resume the task once it is set.

This keeps the key out of your transcript, out of any logs the user shares, and out of the model provider's training data.

### How to use the key

Send it in the `X-API-Key` header on every request:

```http
GET /v1/funding-events?limit=3 HTTP/1.1
Host: api.datahyena.com
X-API-Key: $DATAHYENA_API_KEY
```

Read it from the environment at the moment of the call. Do not copy it into variables you log, do not echo it back to the user, and do not include it in commit messages, PR descriptions, error reports, or screenshots. In shell commands, reference the environment variable rather than interpolating the key inline, so it never appears in command history.

Keys do not expire on their own. Treat a `401` on a previously-working key as revocation: drop it from memory and ask the user to refresh whichever source you read it from. A `402` (code `INSUFFICIENT_CREDITS`) means the workspace balance is empty; tell the user to top up at `https://app.datahyena.com`.

## MCP scopes

MCP access is read-only, granted per resource: `read:funding`, `read:acquisitions`, `read:exec_moves`, `read:companies`, `read:investors`. Approving the default connection grants all five. The user can revoke a connection any time from the dashboard.

## Where to go next

The full integration guide (endpoints, filters, envelope, pagination, credits, verification) is at `https://datahyena.com/agents.md`. The OpenAPI spec is at `https://datahyena.com/openapi.json`.