---
title: "Exchange a short-lived repository-adoption code for a project-scoped API credential and its selected workspace/Product binding."
method: POST
path: "/api/v1/onboarding/repo/exchange"
tags: ["onboarding"]
---

# Exchange a short-lived repository-adoption code for a project-scoped API credential and its selected workspace/Product binding.

`POST /api/v1/onboarding/repo/exchange`

The endpoint first applies a 30-per-15-minute caller-IP limit before parsing the body, then a separate 300-per-hour bucket keyed by the submitted code digest. The raw long-lived key is returned only to the CLI and is never sent to the browser or embedded in the copied shell command. A returning CLI may send its existing pm_live_ Bearer key: if that exact user/workspace write credential is valid, the endpoint binds and reuses it. After a code is consumed, only the exact bound key may resume the same exchanging session; possession of the code alone is insufficient. Success responses set Cache-Control: no-store.

## Request body

- object
  - `code` string, required — The 32-character pm_adopt_ code generated by the authenticated onboarding page. It expires after 15 minutes and is consumed once.

## Response `200`

Code claimed; returns the selected binding and either a newly minted apiKey or reusedCredential:true.

- object

## Other responses

- `400` — Malformed adoption code.
- `401` — A credential supplied for reuse/resume is invalid or expired.
- `403` — Workspace access changed, or the workspace API-key plan limit prevents minting a credential.
- `409` — Code is invalid, already used, or a supplied existing key belongs to another workspace.
- `410` — The unconsumed code expired; generate a new command in Pathmode.
- `429` — Per-IP exchange limit or per-code retry limit exceeded.
- `500` — Credential creation or binding failed.

## Changes

- **2026-08-31** `8ef75cba546a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pathmode/apis/pathmode-api/changes/api/v1/onboarding/repo/exchange/post.md)

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pathmode/apis/pathmode-api/revisions/8ef75cba546a?raw)