Browse documentation›

DocsStart hereAuthentication & limits

Docs · Getting started

Authentication & limits.

One key authenticates all three surfaces: REST, CLI, and MCP. This page is the canonical reference for how that key is presented, what it is allowed to do, how fast you may call, and what comes back when something is refused.

Base URL#

Every endpoint in these docs is relative to one origin. Use it verbatim; the samples in the API reference are generated against the same value.

base url

https://app.argorant.com

1Get a key#

Sign in and mint a key at app.argorant.com/profile → API keys. Keys are prefixed ag_live_ and shown once, so store it before you close the dialog. Name each key after the thing that uses it (zapier, ci, laptop) so you can revoke one without breaking the rest.

2Send it as a Bearer token#

Every request carries the key in the Authorization header. There is no other auth method for the API: no query-string keys, no basic auth.

header

Authorization: Bearer ag_live_…

The CLI reads the same key from argorant login or the ARGORANT_API_KEY environment variable. MCP clients do not use the key at all. They authenticate over OAuth against https://mcp.argorant.com/mcp and act under the same workspace. See Connect a client.

3Verify the key works#

The cheapest possible first call. It spends nothing and tells you which workspace the key belongs to, which scopes it carries, and how much of today's quota is left.

curl

curl "https://app.argorant.com/api/mcp/account" \
  -H "Authorization: Bearer $ARGORANT_API_KEY"

200

{
  "ok": true,
  "email": "you@example.com",
  "role": "owner",
  "scopes": ["argorant:read_counts", "argorant:search_segments",
             "argorant:manage_lists", "argorant:create_exports",
             "argorant:unlock_contacts"],
  "limits": { … },
  "usage":  { … }
}

Scopes#

A key carries scopes; an action needs both its scope and the matching workspace permission. Read actions are free, account actions cost credits, which is why they are separately scoped.

Scope

Cost

Unlocks

argorant:read_counts

Free

Counting a segment and reading account/usage state.

argorant:search_segments

Free

Searching and masked previews.

argorant:manage_lists

Free

Creating and reading saved lists.

argorant:create_exports

Credits

Creating exports and exporting a saved list.

argorant:unlock_contacts

Credits

Revealing contact details and enrichment.

Which tool or endpoint needs which scope is listed per item in the tools reference. An action attempted without its scope returns 403.

Rate limits#

Limits are per key, measured in a sliding one-minute window, and set by the workspace plan. They apply identically to REST, CLI, and MCP traffic, because all three run through the same guard.

Plan

Requests / min

Starter

Pro

120

Scale (incl. Volume and Enterprise tiers)

600

The Free plan has no API, CLI, or MCP access.

Programmatic access starts either with a paid plan or with purchased pay-per-lead credits. A positive credit balance is itself the entitlement and runs at the Starter rate. Until one of those is true, keys can be created but every call is refused with 402 plan_required.

Errors#

Failures are explicit. Read the error field rather than the status code alone, because several conditions share a status.

Status

error

What to do

401

any

The key is missing, malformed, or revoked. Mint a new one.

402

plan_required

The workspace has no plan and no purchased credits. Top up or pick a plan; retrying will not help.

403

any

The key is valid but lacks the scope or workspace permission for this action.

429

rate_limited

You exceeded the per-minute rate. Back off and retry after the window.

A 429 carries Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining headers, plus limit_per_minute and reset_seconds in the body. Honour Retry-After rather than fixed sleeps.

429

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0

{ "error": "rate_limited", "limit_per_minute": 30, "reset_seconds": 37 }

Safe retries#

Endpoints that create something accept an Idempotency-Key header, so a retried request returns the original response instead of creating a second job. The header, the replay semantics, and the signed webhook deliveries are documented on Webhooks & idempotency.

Key in hand?

Run the quickstart end to end: count a market, then pull a verified CSV.

Quickstart API reference Create an account

PreviousQuickstart NextAPI reference