stable · api · 0.1.0
Link an authenticated Platform Account
POST /api/v1/identity-migration-transactions/{transactionId}/link
Capability Domain: Identity Trust
Authentication
platformSession
Scope: None
Parameters and request body
-
transactionId— path, requiredtransactionId schema { "type": "string", "format": "uuid" }
Request schema
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"flow_token"
],
"properties": {
"flow_token": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
}application/json request example
{
"flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}Responses and errors
| Status | Description |
|---|---|
200 | Authenticated link awaits Project Backend confirmation |
401 | Invalid or revoked Project Credential |
403 | Project Credential lacks the required scope |
422 | Request violates the public contract |
200 schema
{
"type": "object",
"additionalProperties": false,
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"project_client_id",
"legacy_subject",
"email",
"locale",
"correlation_id",
"expires_at",
"status",
"account_id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_client_id": {
"type": "string",
"format": "uuid"
},
"legacy_subject": {
"type": "string",
"maxLength": 255
},
"email": {
"type": "string",
"format": "email"
},
"locale": {
"type": "string",
"maxLength": 20
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"pending",
"expired",
"link_pending",
"completed"
]
},
"account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
}
}
}401 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}403 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}422 schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"retryable",
"correlation_id",
"details"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"correlation_id": {
"type": "string",
"format": "uuid"
},
"details": {
"type": "object"
}
}
}
}
}200 example
{
"data": {
"id": "60000000-0000-4000-8000-000000000196",
"project_client_id": "30000000-0000-4000-8000-000000000003",
"legacy_subject": "legacy-42",
"email": "ada@example.test",
"locale": "zh-TW",
"correlation_id": "10000000-0000-4000-8000-000000000196",
"expires_at": "2026-08-02T10:10:00Z",
"status": "link_pending",
"account_id": "20000000-0000-4000-8000-000000000001"
}
}Idempotency
Single-use; retry by the same authenticated Platform Account returns the established link.