Skip to main content
Every request to the Leadterra API must be authenticated with a Bearer token. You include your API key in the Authorization header, and Leadterra uses it to identify your workspace, enforce rate limits, and scope access to your campaigns, sender pools, and leads. There are no session cookies, no OAuth flows, and no multi-step handshakes — just a single header on every call.

​
Getting your API key

Log in to your workspace at app.leadterra.co and go to Settings → API Keys. Click Create new key, give it a descriptive label (for example, production-agent or ci-pipeline), and copy the value immediately — Leadterra only shows the full key once at creation time. Your API key will look like this:
The sk_live_ prefix confirms it is a live key scoped to your production workspace. If you need to test without affecting real campaigns, check whether your workspace supports a sandbox environment with sk_test_ prefixed keys.

​
Making authenticated requests

Include your API key as a Bearer token in the Authorization header of every request.
Here is a complete example that lists the sender pools in your workspace:
Replace sk_live_YOUR_KEY with the key you copied from the dashboard. The same header format applies to every endpoint — GET, POST, or otherwise.
Never share your API key or expose it in client-side code, public repositories, or log output. Anyone with your key can access your workspace, send emails on your behalf, and read your lead data.

​
API key security

Following these practices keeps your key safe and your workspace protected:
  • Use environment variables. Store your key in a variable like LEADTERRA_API_KEY and reference it in code rather than hard-coding the value.
  • Never commit keys to source control. Add .env files to your .gitignore and audit your repository history if you suspect a key was ever committed.
  • Restrict key scope when possible. Create separate keys for separate systems (agents, CI pipelines, local scripts) so you can rotate one without affecting the others.
  • Rotate immediately if compromised. If a key is exposed, go to Settings → API Keys, revoke it, and issue a new one. Update all systems that use the old key before the next deployment.
  • Audit key usage. Review active keys periodically and delete any that are no longer in use.

​
Authentication errors

If your request is rejected due to an authentication problem, the API returns a 401 or 403 status code.
If you keep receiving 401 errors even with what looks like a valid key, make sure there are no extra spaces, newline characters, or truncated characters in the key value — copy-paste errors are the most common cause.