stable · api · 0.1.0

Create an Identity Migration Transaction

POST /api/v1/identity-migration-transactions

Capability Domain: Identity Trust

Authentication

projectCredential (identity-migrations:write)

Scope: identity-migrations:write

Parameters and request body

Idempotency-Key — header, required
Idempotency-Key schema
```
{
    "type": "string",
    "maxLength": 120
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "project_client_id",
        "legacy_subject",
        "email",
        "locale",
        "correlation_id",
        "expires_at"
    ],
    "properties": {
        "project_client_id": {
            "type": "string",
            "format": "uuid"
        },
        "legacy_subject": {
            "type": "string",
            "maxLength": 255
        },
        "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255
        },
        "locale": {
            "type": "string",
            "maxLength": 20
        },
        "correlation_id": {
            "type": "string",
            "format": "uuid"
        },
        "expires_at": {
            "type": "string",
            "format": "date-time"
        }
    }
}

application/json request example

{
    "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"
}

Responses and errors

Status	Description
`201`	Short-lived migration flow; flow_token is creation-only and must be delivered to the MiniCenter registration-or-linking flow
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	Request violates the public contract

201 schema

201 response 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",
                "flow_token"
            ],
            "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"
                },
                "flow_token": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                }
            }
        }
    }
}

401 schema

401 response 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

403 response 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

422 response 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"
                }
            }
        }
    }
}

201 example

201 response 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": "pending",
        "account_id": null,
        "flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
}

Idempotency

Requires Idempotency-Key; retry the identical request after an uncertain response.