# Identity Linking

Source: https://docs.generalaugment.com/guides/identity-linking/
Description: Link messaging identities to app accounts.

Identity linking answers the question: which app user sent this message?

## App-initiated link

Call General Augment when a user adds their phone number in your app settings.

```bash
curl -sS https://api.generalaugment.com/api/v1/integrations/project-id/link-user \
  -H "X-Admin-Key: gaadmlive_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone_e164":"+15551234567","provider_user_id":"user_123","provider_name":"myapp"}'
```

Python:

```python

response = httpx.post(
    "https://api.generalaugment.com/api/v1/integrations/project-id/link-user",
    headers={"X-Admin-Key": "gaadmlive_your_key_here"},
    json={
        "phone_e164": "+15551234567",
        "provider_user_id": "user_123",
        "provider_name": "myapp",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["verified"])
```

## Agent-initiated link

If a new user texts first, the agent can ask for email, send a magic link, and complete linking after OAuth.

## Verification code link

Your app can display a short code. The user sends that code to the agent and General Augment verifies the pending link.

Read [security](/guides/security/) before enabling external API tools.