Authentication

Learn how to authenticate with the GTMAPIs API

API Key Format

GTMAPIs uses API keys for authentication. All API requests must include your API key in the X-API-Key header.

Key Types

Test Keys

gtm_test_1234567890abcdef1234567890abcdef

gtm_live_1234567890abcdef1234567890abcdef

• Test keys (gtm_test_*) - For development and test integrations
• Live keys (gtm_live_*) - For production integrations

Test and live prefixes identify intended usage. Both must be valid account keys and both follow the normal access, rate-limit, and credit policy unless product docs state otherwise.

Never commit API keys to version control or expose them in client-side code. Store them as environment variables.

Making Authenticated Requests

Include your API key in the X-API-Key header with every request:

cURL

curl -X POST https://api.gtmapis.com/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -d '{"email":"[e-mail]"}'

const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef'
};

const response = await fetch('https://api.gtmapis.com/v1/validate', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({ email: '[e-mail]' })
});

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'gtm_test_1234567890abcdef1234567890abcdef'
}

response = requests.post(
    'https://api.gtmapis.com/v1/validate',
    headers=headers,
    json={'email': '[e-mail]'}
)

Generating API Keys

1. Login to Dashboard

   Go to gtmapis.com/dashboard

2. Navigate to API Keys

   Click on API Keys in the sidebar

3. Create New Key

   Click Generate New Key and choose test or live mode

4. Save Your Key

   Copy the full key immediately - it’s only shown once!

API keys are stored as SHA-256 hashes for security. You’ll only see the full key once during creation.

Scoped Keys for Agents and Automations

Create restricted keys for integrations, contractors, automations, and MCP-enabled agents instead of sharing an unrestricted live key.

Current public scopes:

Scope	Permits
credits:read	Credit balance inspection through GET /v1/credits and the gtmapis_get_credits MCP tool.
email:validate:single	Single-email validation through POST /v1/validate and the gtmapis_validate_email MCP tool.
email:validate:bulk	Synchronous bulk validation through POST /v1/validate/bulk, async validation jobs through POST /v1/validate/batch, signed CSV upload through /v1/csv/prepare-upload and /v1/csv/start-processing, job reads through /v1/csv/jobs/*, and the bulk/job MCP tools.

For an agent that only needs to inspect docs, do not provide a key. For an agent that only checks balances, grant only credits:read. For an agent that validates one-off emails, grant only email:validate:single. For an agent that validates lists, grant email:validate:bulk and prefer /v1/validate/bulk over many single-email calls.

See MCP and Agent Tools for Claude Desktop and generic MCP client configuration.

Hosted MCP Authentication

Hosted MCP uses a different credential model from the public API. Remote MCP clients connect to https://www.gtmapis.com/api/mcp and complete an OAuth-style PKCE flow. GTMAPIs issues bearer tokens scoped to hosted MCP, with expiry and revocation support.

Do not paste public API keys into hosted MCP clients, and do not use hosted MCP bearer tokens for public API calls. Public API requests continue to use X-API-Key.

API Key Security

Best Practices

✅ Do:

• Store API keys as environment variables
• Use test keys for development
• Rotate keys regularly
• Use separate keys for different environments
• Revoke compromised keys immediately

❌ Don’t:

• Commit keys to version control
• Share keys in public forums or Slack
• Use live keys in development
• Expose keys in client-side JavaScript
• Hardcode keys in your source code

Key Storage Example

.env

# Store in .env file (never commit this!)
GTMAPIS_API_KEY=gtm_test_1234567890abcdef1234567890abcdef

// Load from environment
const apiKey = process.env.GTMAPIS_API_KEY;

const response = await fetch('https://api.gtmapis.com/v1/validate', {
  headers: {
    'X-API-Key': apiKey
  }
});

# Load from environment
import os
api_key = os.environ.get('GTMAPIS_API_KEY')

response = requests.post(
    'https://api.gtmapis.com/v1/validate',
    headers={'X-API-Key': api_key}
)

Rate Limits

Each API key has a public API rate limit of 10,000 requests per minute. IP-based abuse protection may also apply at 1,000 requests per minute per IP address.

If you exceed this limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 10000 requests per minute",
  "retry_after": 60
}

For higher rate limits, contact us at [e-mail]

Error Responses

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Missing API Key

{
  "error": "Unauthorized",
  "message": "X-API-Key header is required"
}

Expired or Revoked Key

{
  "error": "Unauthorized",
  "message": "API key has been revoked"
}

Next Steps

Make Your First Request

Try the API with your new key

API Reference

Explore all available endpoints