Getting Started

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.

curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'
{ "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:

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.

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

4. Verify it works

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.

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.

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:

{
  "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.

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.

# 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.

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