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

# Start linking an external identity

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

Begins the OpenID Connect authorization-code flow for `provider` and returns the URL to send the browser to. The flow is completed by `POST /v1/identities/{provider}/link/complete` with the `code` and `state` the provider redirects back with. Requires a signed-in session (not an API key).

## Path parameters

- `provider` string, required — Identity provider key, e.g. `world-sandbox`.

## Request body

- IdentityLinkStartRequest
  - `returnTo` string — Dashboard path to return to after the link completes (same-origin path only, e.g. `/wallet?promoResume=1`).

## Response `201`

Pending link created; redirect the browser

- IdentityLinkStartResponse
  - `authorizationUrl` string, uri, required — Send the browser here to authenticate at the provider.
  - `expiresAt` string, date-time, required — The pending link must be completed before this instant.

## 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`)
- `429` — Too many link attempts (`IDENTITY_LINK_RATE_LIMITED`)
- `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/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/99cc8f5bdff4?raw)