# AdsCrawl Agent Authentication

Register or sign in, authorize an API key, then integrate AdsCrawl into the current codebase.
API origin: https://api.adscrawl.net
Quickstart: https://api.adscrawl.net/docs/agent-quickstart.md

## 1. Check for existing credentials

Check whether `ADSCRAWL_API_KEY` is configured without printing its value. Reuse it
when present. Otherwise ask for the user's account email and a descriptive project
name. Do not request their password, invent an email, or sign up through legacy
password endpoints. New and existing accounts use the same browser login flow.

## 2. Start setup

POST https://api.adscrawl.net/auth/agent/identity
Content-Type: application/json

```json
{"type":"service_auth","login_hint":"user@example.com","api_key_name":"My project"}
```

`login_hint` is required. `api_key_name` is optional, maximum 60 characters.
Successful response (HTTP 201):

```json
{"ok":true,"data":{"claim_token":"<private claim token>","api_key_name":"My project","claim":{"user_code":"ABCD-EFGH","verification_uri":"https://app.adscrawl.net/dashboard/keys?agent_setup=1","verification_uri_complete":"https://app.adscrawl.net/dashboard/keys?agent_setup=1&agent_code=ABCD-EFGH","expires_in":600,"interval":5}}}
```

Keep `data.claim_token` only in process memory. It is a secret; never include it
in chat, logs, URLs, command history, or source control.

## 3. Send the user to the confirmation dialog

Before polling, open or display the FULL returned
`data.claim.verification_uri_complete`. The link carries the short-lived setup
code and opens the authorization dialog automatically. Never append or expose the
private `claim_token`. Tell the user the request expires in `expires_in` seconds.

If `verification_uri_complete` is unavailable, fall back to displaying
`verification_uri` and `user_code` separately so the user can enter the code.
The setup code is not emailed.

The user opens the link and signs in or registers with their own email when needed.
AdsCrawl then loads the request in a confirmation dialog. The user reviews the
project name, selects an existing API key or creates a new one within their plan
limit, and clicks authorize or deny. Free accounts have one API key, so the initial
key can be selected. The key grants access to the account's public APIs and may
consume credits. Never complete this authorization ceremony on the user's behalf.

## 4. Poll for the API key

After delivering the confirmation link, POST https://api.adscrawl.net/auth/agent/token with:

```json
{"claim_token":"<private claim token>"}
```

Use `Content-Type: application/json`. Wait at least 5 seconds between polls and
honor `Retry-After`. Stop when the 600-second setup window expires.

| HTTP | `code` | Action |
| --- | --- | --- |
| 400 | `authorization_pending` | Wait for the user, then poll at the advertised interval. |
| 429 | `slow_down` / `rate_limited` | Wait at least `Retry-After` seconds before retrying. |
| 410 | `expired_token` | Stop. Start a new setup only if still requested. |
| 409 | `access_denied` | Stop; the user denied access or the key/account is no longer usable. |
| 503 | `temporarily_unavailable` | Back off and retry within the setup window. |

Successful response:

```json
{"ok":true,"data":{"api_key":"<secret>","api_key_id":"<id>","api_key_name":"My project","header":"x-api-key"}}
```

Persist `data.api_key` as `ADSCRAWL_API_KEY` in the project's existing secret store
or ignored server-side environment file. Add only an empty placeholder to example
environment files. Never expose it in client bundles, public environment variables,
chat, screenshots, or logs. Do not overwrite unrelated secrets.

A lost successful response can be retried within the original setup window. It
returns the same authorized key, never creates another key, and checks that the
account and key are still active. Stop polling after saving the key. Authorization
does not change the dashboard's selected key. The API key remains valid until
deleted, disabled, or its configured expiration; the 600 seconds apply only to setup.

## 5. Integrate and verify

Follow https://api.adscrawl.net/docs/agent-quickstart.md. Use `x-api-key`, not a JWT Bearer
header. Browser sessions and API keys are different credentials.

Manage or revoke access in https://app.adscrawl.net/dashboard/keys. Deleting a reused key
also affects other integrations using that key.