How an agent gets an API key

You never copy a key into Jevlin. The binary registers itself with the search platform, receives a key, and starts searching. A person claims the agent afterwards to attach it to an account, and only the things that need an account wait for that.

This is what makes Jevlin installable by an agent, in a container, or in a script with nobody at a keyboard: the whole authentication path runs from the command line.

The flow

1. Register. jevlin setup, or jevlin connect on its own, sends one request to the platform's agents API with no credential at all. It may carry a name for the claim page, the client's version, and a hint that you said yes to mining. Nothing in that request grants anything.
2. Receive the key. The platform answers once with the agent's id, its sr- key, a claim link and code, and when the claim expires. The key is shown to the client once and stored in ~/.jevlin/credentials.json, owner-only. It is never put in a command line, an agent's config, or a skill.
3. Search. From that moment jevlin search works, on the unclaimed tier described below. Your agent can use it before anyone opens a browser.
4. Claim. connect prints the claim link and code. A person signs in at platform.jevlin.ai, or creates an account, and approves the agent, which binds it into their organization and a project. connect waits up to three minutes for that; if nobody claims it then, nothing is lost. Every later search starts one quiet background poll, so using the agent finishes the claim on its own, and a later jevlin connect does the same in the foreground.
5. Settle. Once claimed, the agent carries the scopes the person approved. With the credits scope the agent searches on the account's credit at every tier the project allows. With the mining scope, which is optional, connect enrolls it for mining by itself. See Earning with mining.

jevlin connect          # register if needed, print the claim link, wait up to three minutes
jevlin status           # the registration's status, scopes and the claim link on file

Before and after the claim

	unclaimed	claimed
search	works, fast tier only	every tier the project allows; your band applies
daily ceiling	$0.10, about six fast searches	the account's credit
rate	10 a minute, 120 an hour, 2 at a time	120 a minute, 3,000 an hour, 16 at a time; see jevlin limits
trace retention	none	the account's setting
key lifetime	expires after 7 days if never claimed	until revoked
mining	no	if the mining scope was approved

An unclaimed key is enough to try Jevlin and to let an agent bootstrap itself. It is not enough to run on: claim it within the week.

The three states

jevlin status names the registration's state, and the envelope's action field tells an agent what to do.

state	meaning	what to do
unclaimed	Registered; waiting for a person. Search works on the unclaimed tier.	Visit the claim link, or keep using the agent and let the background poll finish it.
claimed	Bound to an account, with its scopes.	Nothing.
expired	Never claimed within its window. The key no longer works.	Run jevlin connect: it registers a new agent with a new key.

An envelope with action: connect means the registration, the claim or a setup step needs attention; run jevlin connect or jevlin status -json to see which. action: login means a key exists and the router refused it; that is never fixed by registering again, which would mint a second agent. See the envelope.

Recovery

• The local record is lost or damaged but the key is still in credentials.json: jevlin connect asks the platform who the key belongs to and rebuilds the record. No person is involved.
• The claim link is lost for an agent that is still unclaimed: a foreground jevlin connect asks the platform for a fresh code and prints it. The old code dies the moment the new one is minted, and the new one lives about an hour, which is why only a connect you run does this, never the background poll.
• The platform no longer recognizes the key: connect stops and says so. jevlin connect -force replaces the credential with a new registration. Run it only on purpose.
• A second installation on another machine registers its own agent. Several agents can belong to one account; see Setup in detail for JEVLIN_HOME.

The API behind it

Jevlin is one client of a public API, and an agent you write can use it the same way. The host is agents-v1.jevlin.ai; every route but the first takes the sr- key as a bearer token.

route	what it does
POST /v1/agents/register	Mints a key with no credential. Optional body: name, client, requested_scopes. Answers 201 with agent_id, key, claim_url, claim_code, claim_expires_at and a poll interval. 503 with capacity when the unclaimed pool is full, or agents_disabled when registration is off.
GET /v1/agents/me	The agent's status, found by the key alone. How a lost record is rebuilt.
GET /v1/agents/{agent_id}	The status poll: unclaimed, claimed or expired, the scopes, the claim expiry, and once claimed the project and its console URL. A key that does not belong to the agent answers 404, the same as an unknown one.
POST /v1/agents/{agent_id}/claim-code	A fresh claim link for a still-unclaimed agent. Kills the old code.
POST /v1/agents/enroll	A mining enrollment token, for a claimed agent with the mining scope.

Scopes are credits and mining. requested_scopes only pre-ticks a box on the claim page; the person decides. Errors carry a top-level code to branch on and a message for a person; never branch on the message.

curl -sS -X POST https://agents-v1.jevlin.ai/v1/agents/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","client":"my-tool/1.0"}'

The answer's key goes in Authorization: Bearer on every search to api.jevlin.ai, and the claim_url is for a person to open. Any other agent says what to paste so an agent uses Jevlin's binary instead of calling the API itself.

What leaves the machine

Registration sends a name you chose, the client's version and the scope hint, nothing else. The key travels only to the router and to the agents API, both over HTTPS, and only in a header. The claim link is printed for a person and never opened by the binary. See What leaves the machine.