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: 
sk_live_YOUR_KEY
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. 
Authorization: Bearer sk_live_YOUR_KEY
Here is a complete example that lists the sender pools in your workspace: 
curl https://app.leadterra.co/v1/sender-pools \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
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.
StatusMeaningWhat to do
401 UnauthorizedNo Authorization header was sent, or the header is malformed.Confirm the header is present and formatted as Bearer sk_live_YOUR_KEY.
401 UnauthorizedThe API key is invalid or has been revoked.Verify the key value in your dashboard. If it was revoked, create a new one.
403 ForbiddenThe key is valid but does not have permission to perform this action.Check that you are using the correct key for this workspace and that the key has not been restricted.
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.