---
title: "Refresh a short-lived clone-invocation access token."
method: POST
path: "/v1/refresh_external_authorization"
tags: ["External Authorization"]
---

# Refresh a short-lived clone-invocation access token.

`POST /v1/refresh_external_authorization`

## Request

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

Use the grant-lifetime refresh token before the access token expires. The refresh token is bound to the same authenticated application, installation, and external identity. Concurrent or repeated refreshes return the same current access token and never extend the owner-approved grant expiry. The response includes `clone_ids` and `clone_nicknames` so partners can keep display names warm across token rotation.

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `refresh_token` string, required: Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret.
  - `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.
  - `idempotency_key` string, nullable: A stable opaque event key that makes exact retries return the same outcome.

## 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
  - `status` 'active' | 'revoked' | 'expired', nullable, required: Current authorization or invocation lifecycle state.
  - `access_token` string, nullable, required: Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.
  - `refresh_token` string, nullable, required: Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret.
  - `token_type` 'Bearer', nullable, required: Authorization token type.
  - `grant_id` string, nullable, required: Stable grant identifier used by the owner-facing revocation surface.
  - `scopes` string[], nullable, required: Capabilities approved by the owner.
  - `clone_ids` string[], nullable, required: AI consciousness resources selected by the owner.
  - `clone_nicknames` object, nullable, required: Map of granted clone id to plaintext display nickname (same shape as exchange).
  - `access_token_expires_at` integer, nullable, required: UNIX timestamp after which the short-lived access token must be refreshed.
  - `expires_at` integer, nullable, required: UNIX timestamp when this resource or capability expires.

## 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)