---
title: "Complete linking an external identity"
method: POST
path: "/v1/identities/{provider}/link/complete"
tags: ["Identities"]
---

# Complete linking an external identity

`POST /v1/identities/{provider}/link/complete`

Exchanges the provider's authorization `code` (using the pending link identified by `state`) and links the verified identity to the signed-in user. The pending link is single-use and expires 10 minutes after it was started.

## Path parameters

- `provider` string, required

## Request body

- IdentityLinkCompleteRequest
  - `state` string, required
  - `code` string, required

## Response `200`

Identity linked (or re-verified)

- IdentityLinkCompleteResponse
  - `provider` 'clerk' | 'aep' | 'world' | 'world-sandbox', required
  - `verified` boolean, required
  - `firstLink` boolean, required — True when this call created the identity link.
  - `returnTo` string — The `returnTo` supplied when the link was started.

## Other responses

- `400` — Bad request — input failed validation
- `401` — Unauthorized — missing or invalid credentials
- `403` — Not a session credential (`IDENTITY_LINK_REQUIRES_SESSION`)
- `404` — Unknown or disabled provider (`IDENTITY_PROVIDER_UNKNOWN`)
- `409` — Identity belongs to another user (`IDENTITY_ALREADY_LINKED`) or the user already holds a different identity from this provider (`IDENTITY_USER_ALREADY_LINKED`)
- `500` — Internal server error
- `502` — Identity provider unavailable (`IDENTITY_PROVIDER_UNAVAILABLE`)

## Changes

- **2026-09-25** `5abada71ceae` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/monid/apis/monid-api/changes/v1/identities/:provider/link/complete/post.md)

---

[API](https://skmtc.dev/monid/apis/monid-api.md) · [All operations](https://skmtc.dev/monid/apis/monid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/monid/apis/monid-api/revisions/5abada71ceae?raw)