---
title: "Start passwordless grant issuance for an external identity and installation."
method: POST
path: "/v1/create_external_authorization_request"
tags: ["External Authorization"]
---

# Start passwordless grant issuance for an external identity and installation.

`POST /v1/create_external_authorization_request`

## Request

- Base URL: `https://partner.mindupload.app`
- URL: `https://partner.mindupload.app/v1/create_external_authorization_request`
- Auth: API key in header `X-Partner-Key`

Use this when a person on your platform already has a Mind Upload account. Store the returned device code only for the short authorization window. Show the user code and verification link to the person; they review the application, requested scopes, and selected AI consciousnesses on Mind Upload.

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `idempotency_key` string, required: A stable opaque event key that makes exact retries return the same outcome.
  - `installation_id` string, required: Your stable opaque identifier for this app installation.
  - `external_subject` string, required: Your stable opaque identifier for the person authorizing this installation.
  - `installation_label` string, nullable: Optional user-readable name for the installation shown during consent.
  - `external_identity_label` string, nullable: Optional user-readable external identity shown during consent.
  - `requested_scopes` string[], required: Capabilities the owner is being asked to delegate.

## Response `200`

Result envelope — check the success field.

- object
  - `success` boolean, required: Whether the call succeeded.
  - `error_message` string, nullable, required: Human-readable reason when success is false.
  - `error_code` string
  - `device_code` string, nullable, required: Short-lived high-entropy secret used only to poll and exchange this request.
  - `user_code` string, nullable, required: Short-lived human-entered code shown to the owner.
  - `verification_uri` string, nullable, required: Mind Upload location where the owner reviews the request.
  - `verification_uri_complete` string, nullable, required: Verification location with the human code prefilled.
  - `expires_in` integer, nullable, required: Seconds until the device authorization request expires.
  - `poll_interval` integer, nullable, required: Minimum seconds to wait between exchange polls.
  - `grant_duration_seconds` integer, nullable, required: Grant lifetime shown to the owner before consent.

## Other responses

- `400`: Invalid request payload.
- `401`: Missing or invalid partner key.
- `403`: Partner is not authorized for this operation.
- `429`: Rate limit exceeded — retry later.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mindupload/apis/mind-upload-partner-api.md) · [All operations](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/revisions/0371bdf78533?raw)