Access Keys and Rate Limits¶

Every agent's URL is on the public internet, and each request can spend your model provider's credits. Two controls decide who gets through.

Public and private agents¶

Access	Who can call the URL
`private` (default)	Only requests with `Authorization: Bearer agk_…`, where the key is one of this agent's access keys.
`public`	Anyone with the URL.

Don't rely on the URL staying secret. Each agent's hostname appears in public certificate transparency logs as soon as its certificate is issued, and automated scanners start requesting new hostnames within minutes. Make an agent private whenever it spends your money or exposes anything you don't want public.

In the console¶

New agents are private, and creating one shows its first key (labelled default) once. Afterwards, open the agent and find Access to:

create another key: enter a label (e.g. website) and click New key, then copy it, since it's only shown once;
revoke a key with its trash icon;
switch the agent between Private and Public.

A private agent whose keys have all been revoked refuses every request.

With the API¶

# Create a key
curl -X POST https://agntapi.agntspark.com/v1/agents/agt_…/access-keys \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" -H 'content-type: application/json' \
  -d '{"label": "website"}'
# → {"id": "…", "label": "website", "key_preview": "agk_Xy12abcd...", "created_at": "…", "key": "agk_…"}

# Make the agent private
curl -X PATCH https://agntapi.agntspark.com/v1/agents/agt_… \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" -H 'content-type: application/json' \
  -d '{"access": "private"}'

POST /v1/agents creates private agents unless you send "access": "public". The response's access_key holds the new agent's first key; it's the only time that key is returned.

Calling a private agent¶

curl -X POST https://support-k3v9qa.run.agntspark.com/invoke \
  -H "Authorization: Bearer agk_…" \
  -H 'content-type: application/json' \
  -d '{"input": "Hello"}'

Without a valid key the platform answers 401 with WWW-Authenticate: Bearer, before the request reaches your agent.

Rotating a key¶

Keys don't expire. To rotate one without downtime: create a new key, update your callers, then revoke the old one.

curl -X DELETE https://agntapi.agntspark.com/v1/agents/agt_…/access-keys/<key id> \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY"

Revocation takes effect on the next request.

Keys in browsers

A key embedded in a web page or mobile app can be extracted. For a public website, call your agent from your own backend and keep the key there.

Rate limits¶

Two limits apply to every agent URL, public or private.

Limit	Default	What happens past it
Per caller: requests per minute from one IP address	120, or the agent's `rate_limit_rpm`	`429` with `Retry-After`
Per agent: requests per minute across all callers	Set by your plan (free: 300, pro: 3,000)	`429` with `Retry-After`

Limits are counted in fixed one-minute windows. The per-caller limit is checked before the access key, so unauthorized callers can't use up your real callers' allowance.

Set the per-caller limit in the console under Access, or:

curl -X PATCH https://agntapi.agntspark.com/v1/agents/agt_… \
  -H "Authorization: Bearer $AGNTSPARK_API_KEY" -H 'content-type: application/json' \
  -d '{"rate_limit_rpm": 30}'

Send "rate_limit_rpm": null to go back to the default.

Tip

If your backend calls the agent for many end users, all those requests come from your backend's IP. Raise rate_limit_rpm accordingly, and rate limit your own users in your backend.

Responses from the platform¶

These come from AgntSpark's edge, not your agent, and are plain text:

Status	Meaning
`401`	The agent is private and the request had no valid access key.
`404`	No agent has this hostname.
`429`	A rate limit was hit; retry after `Retry-After` seconds.
`503`	The agent has no running replica.