Account Linking

Account linking connects multiple authentication methods to a single user account. This means a user can sign in with any of their linked providers and access the same account.

How It Works

When a user signs in with a social provider (GitHub, Google, etc.), Aero2 creates an identity record that links the provider's account to the local user. A single user can have multiple linked identities.

Example: A user signs up with GitHub. Later, they also sign in with Google using the same email address. Both the GitHub and Google identities are linked to the same Aero2 user account.

Automatic Linking

Aero2 automatically links identities when all of the following conditions are met:

1. A user signs in with a new provider.
2. The email address from the new provider matches an existing user account.
3. The email address is verified by the provider.

When these conditions are met, the new identity is linked to the existing account rather than creating a duplicate user.

API Endpoints

List linked identities

Retrieve all identities linked to a user:

curl https://your-app.aero2.dev/api/users/:id/identities \
  -H "Authorization: Bearer <access_token>"

[
  {
    "id": "ident_abc123",
    "provider": "github",
    "provider_user_id": "12345",
    "email": "jane@example.com",
    "created_at": "2026-01-15T10:00:00Z"
  },
  {
    "id": "ident_def456",
    "provider": "google",
    "provider_user_id": "67890",
    "email": "jane@example.com",
    "created_at": "2026-02-01T14:30:00Z"
  }
]

Unlink an identity

Remove a linked identity from a user account:

curl -X DELETE https://your-app.aero2.dev/api/users/:id/identities/:identity_id \
  -H "Authorization: Bearer <access_token>"

Key Points

• Users can have multiple linked identities but only one primary email address.
• The primary email is used for communications and as the unique identifier within the application.
• Linking is based on verified email address matching — unverified emails are not automatically linked.