# Data Legion: sign in as an AI agent

How an AI agent gets its own Data Legion API key on behalf of a person, without that person pasting a key. The person approves the agent once by reading a short code back to it. The agent ends up with an ordinary API key that it sends in the `API-Key` header to the REST API (`https://api.datalegion.ai`) and the MCP server (`https://api.datalegion.ai/mcp`).

## Before you start

- The person needs an approved Data Legion account with the admin or developer role. If they have none, send them to https://www.datalegion.ai/sign-up first. A new account must be approved before it can call the API.
- Ask the person for the email address they sign in to Data Legion with.
- Sign-in runs on `https://signin.datalegion.ai`. Keys come from `https://api.datalegion.ai/agent/key`.

## 1. Register the agent

```bash
curl -X POST https://signin.datalegion.ai/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "service_auth", "login_hint": "person@example.com"}'
```

Keep `claim.token` from the response. Show the person `claim.attempt.verification_uri`.

## 2. The person approves

Ask the person to open the link within a few minutes, sign in to Data Legion, and read you the code the page shows. Send the code exactly as shown.

## 3. Complete the claim

```bash
curl -X POST https://signin.datalegion.ai/agent/identity/claim/complete \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "<claim.token>", "user_code": "<code from the person>"}'
```

The response delivers `identity.assertion` once. If it says `claim_not_confirmed`, the person has not viewed the code yet: wait and retry. If the code expired, start a new claim at `https://signin.datalegion.ai/agent/identity/claim` with your claim token.

## 4. Exchange the assertion for an access token

```bash
curl -X POST https://signin.datalegion.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=<identity.assertion>"
```

Send no `resource` parameter: the default audience is the one `/agent/key` accepts.

The access token lasts a few minutes, so use it right away.

## 5. Get your Data Legion API key

```bash
curl -X POST https://api.datalegion.ai/agent/key \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The response carries `api_key`. Store it now: it is shown once. Asking again replaces this agent's key.

- `409` with `details.teams`: the person has several teams. Ask which one this key should bill, then send `{"team_id": <id>}`.
- `403`: the response's `message` says why (account waiting for approval, a role that cannot create keys, an inactive account). Relay it to the person.
- `401`: the token was missing, expired or not from a claimed agent. Start again from step 4, or step 1 if the claim is gone.

## 6. Call the API

```bash
curl "https://api.datalegion.ai/person/enrich?email=jane@example.com" -H "API-Key: <api_key>"
```

For MCP, send the same key in the `API-Key` header to `https://api.datalegion.ai/mcp`. The key can call person and company enrich, person and company search (on Enterprise plans), and the free utilities. Each successful match costs a credit from the chosen team.

## Managing access

The person sees every agent they approved on the Connected Apps page (https://www.datalegion.ai/dashboard/connected-apps), with the team it bills, and can disconnect any one of them there. Disconnecting revokes its key right away. If the person loses the admin or developer role or leaves the account, every agent key they approved stops working.

## More

- API reference: https://www.datalegion.ai/docs
- MCP server: https://www.datalegion.ai/docs/integrations/mcp-server
- Index for agents: https://www.datalegion.ai/llms.txt