> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get credentials

> Sign up, create an API key and set STOPHY_API_KEY. An agent can sign up through the API and collect a key after you approve. Check, rotate and revoke keys.

Every Stophy call takes an API key. Sign up, create a key, and set it as `STOPHY_API_KEY`.

## Get a key

1. Sign up at [stophy.dev/signup](https://stophy.dev/signup) with GitHub or Google. A new account starts with a free balance, shown on [Pricing](https://docs.stophy.dev/account/pricing.md).
2. Create a key on the [API keys](https://stophy.dev/app/api-keys) page.
3. Set it in your environment. The [SDKs](https://docs.stophy.dev/sdks.md), the [CLI](https://docs.stophy.dev/install-cli.md) and the MCP package read it from there.

```bash theme={null}
export STOPHY_API_KEY="<your key>"
```

Send it on every call as `Authorization: Bearer $STOPHY_API_KEY`. Every key on an account spends from one balance. Keep keys in a server secret store, never in committed code or browser code.

## Other ways to sign in

| You use | Do this | You get |
| - | - | - |
| The [CLI](https://docs.stophy.dev/install-cli.md) | `stophy login` | A key saved on this computer. Logging in again replaces it. |
| An [MCP client](https://docs.stophy.dev/install-mcp.md) | Connect `https://mcp.stophy.dev/mcp` and approve in the browser | Every MCP tool, with no key to copy |
| An agent with no key | [Sign up from an agent](#sign-up-from-an-agent) | A key, after you approve |

## Sign up from an agent

An agent asks for an account, and you approve it in the browser. Over MCP, the `stophy_signup` tool runs the same two steps. Both calls are free and take no key.

1. Start a signup:

   ```bash theme={null}
   curl -X POST https://api.stophy.dev/v1/signup \
     -H "Content-Type: application/json" \
     -d '{}'
   ```

   It answers `201`:

   ```json theme={null}
   {
     "success": true,
     "data": {
       "claimUrl": "https://stophy.dev/claim/…",
       "code": "…",
       "expiresAt": "2026-11-21T20:49:06.340Z"
     }
   }
   ```

2. Give your person the `claimUrl`. They sign in with GitHub or Google and approve. Keep `code` secret. Both expire at `expiresAt`, 24 hours after the signup.

3. Poll with the `code` every few seconds:

   ```bash theme={null}
   curl -X POST https://api.stophy.dev/v1/signup/poll \
     -H "Content-Type: application/json" \
     -d '{"code":"<code>"}'
   ```

   Until your person approves, it answers `202` with `"status": "waiting"`. After that it answers `200` with `data.apiKey`, once. Save the key where your person agreed.

| Code | Cause | Fix |
| - | - | - |
| `404 notFound` | The code is unknown, expired, or its key was already collected | Sign up again |
| `429 rateLimited` | Too many signups from one IP address today ([limit](https://docs.stophy.dev/production/rate-limits.md)) | Wait `retryAfterSeconds`, or sign up at [stophy.dev/signup](https://stophy.dev/signup) |

## Check a key

`GET /v1/limits` is free. It returns `balanceUsd`, `rateLimit` and `keyExpiresAt`, which is `null` for a key that never expires, such as one an agent collected. A wrong, revoked or expired key answers `401 unauthorized`, with `signupUrl` and `signup` for a new one.

## Rotate or revoke a key

To rotate, create the new key, deploy it, then revoke the old one. `DELETE /v1/key` revokes the key you send it with, at once, for free. `stophy logout` revokes the CLI's key. Filter [`GET /v1/logs`](https://docs.stophy.dev/account/usage#list-calls) by `apiKeyId` to see one key's calls.

## Calls without a key

Search, scrape, map and parse also answer without a key, within the [keyless limits](https://docs.stophy.dev/production/rate-limits.md#without-a-key), first page only. A parser works without a key when `keyless` is `true` in `GET /v1/parsers`. Everything else answers `401 apiKeyRequired` with `signupUrl` for a person and `signup` for an agent, and so does a keyless call that sends one of these:

| Needs a key | On |
| - | - |
| `page` other than 1, `cursor` | Every endpoint that pages |
| `actions`, `profile`, `waitFor`, `checkPromptInjection`, `onlyCleanContent`, `redactPII`, `audio`, `video`, `json` with a `schema` or `prompt` | Scrape |
| A parser not marked `keyless`, or any parser option | Scrape |
| `scrapeOptions` | Search |
| `includeSubdomains: true` | Map |
| A file over the keyless size limit | Parse |
| Every call | Crawl, batches, extract, agent, browsers, monitors, webhooks |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.