> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://gtm-tools.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server.

# Getting Your API Key

> Get a key, verify the email, and start calling tools

API keys are issued after email verification. The whole flow takes under a minute.

## Steps

### 1. Request a key

Call `get_api_key`. No auth required for this endpoint.

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'
```

```json
{ "status": "verification_sent", "email": "you@yourcompany.com" }
```

### 2. Verify the email

Open your inbox: you'll receive a message with a short verification code. Call `get_api_key` again with the same email plus the `code` to finalize the key:

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com", "code": "123456"}'
```

The response returns your API key, prefixed `sk_`. It's only displayed once, so save it now.

### 3. Store the key

Set it as an environment variable.

```bash
# macOS / Linux
export GTM_TOOLS_API_KEY="sk_..."

# Persist across shells
echo 'export GTM_TOOLS_API_KEY="sk_..."' >> ~/.zshrc
```

### 4. Verify it works

```bash
curl https://api.gtm-tools.sh/api/v0/get_credit_balance \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY"
```

You should see your balance (100 for new accounts) and the per-tool cost map.

> **Tip**
>
> Using the CLI? `gtm-tools admin login` replaces all four steps with one browser sign-in and stores the key at `~/.gtm-tools/config.json` (chmod 600). Agents with no human present can register themselves through [auth.md](/integrations/agent-onboarding#autonomous-registration-via-authmd).

## Using your API key

Every call carries the key as a bearer token, whichever transport you use:

```
Authorization: Bearer sk_...
```

MCP clients take it in the same header:

```json
{
  "mcpServers": {
    "gtm-tools": {
      "url": "https://api.gtm-tools.sh/mcp",
      "headers": { "Authorization": "Bearer sk_..." }
    }
  }
}
```

Clients that support remote MCP OAuth can point at the bare `https://api.gtm-tools.sh/mcp` and authenticate in-flow instead. See [MCP](/integrations/mcp).

## Managing keys

Keys are not scoped: any key in a workspace can call any tool and draws on the same wallet. What you can do is audit and revoke.

```bash
# Every key in the workspace, values obfuscated
gtm-tools admin keys list

# Revoke one by id
gtm-tools admin keys revoke apikey_01...
```

The same operations exist over MCP and REST as `list_api_keys` and `revoke_api_key`, both free. A key can only revoke keys in its own workspace.

> **Warning**
>
> `gtm-tools admin login` revokes the workspace's previous `CLI (…)`-named keys before minting a new one. Convenient for humans, destructive if you embedded one of those keys in CI. For anything long-lived, mint a key with `get_api_key` and leave it alone.

Rotating a key means getting a new one the same way, then revoking the old one.

## Free tier

New accounts receive **100 free credits**. That's enough for \~6 LinkedIn employee searches, \~20 email lookups, or \~6 full signal sweeps. Top up with `buy_credits` when you need more, or set `set_auto_reload` once and stop thinking about it. Free tools (every billing tool, `detect_signal` as a dispatcher, the session reads) never draw on the balance at all.

## Troubleshooting

* **No verification email**: check spam. The verification message comes from a `noreply@…` sender.
* **`401 Unauthorized` on a known-good key**: see [401 Unauthorized](/knowledge-base/troubleshooting/unauthorized).
* **`402 Insufficient Credits`**: see [402 Insufficient Credits](/knowledge-base/troubleshooting/insufficient-credits).
* **`try_again_later` on `get_email`**: see [Why did I get try_again_later?](/knowledge-base/troubleshooting/try-again-later).