---
title: "Exchange a Locus OAuth token for a scoped CLI credential"
method: POST
path: "/credits/cli/credential"
tags: ["Authentication"]
---

# Exchange a Locus OAuth token for a scoped CLI credential

`POST /credits/cli/credential`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/cli/credential`
- Auth: OAuth 2
  - Authorization code: `https://api.paywithlocus.com/api/credits/mcp/oauth/authorize`
  - Token URL: `https://api.paywithlocus.com/api/credits/mcp/oauth/token` scopes: `mcp:read`, `mcp:execute`

Exchanges a Locus MCP OAuth access token (mcp:read and mcp:execute) for one lcac_ execution credential bound to that OAuth connection. Refreshing the OAuth token keeps the same binding. The credential expires 7 days after its last use and never later than 30 days after issue. It stops working when the signed-in account loses execute access to the workspace. Generate registrationToken locally from exactly 24 random bytes encoded as unpadded base64url. Replaying the token renews the credential unchanged; a new token rotates it in place. A revoked credential is never renewed or rotated. tools behaves as on the Okibi route. hostname is optional and names the credential "Locus CLI (<hostname>)" in the dashboard.

## Request body

- object
  - `registrationToken` string, required: Canonical base64url encoding of 24 bytes generated by a cryptographically secure random-number generator.
  - `tools` object: Optional endpoint allowlist. Omit it to leave the credential unrestricted within the workspace's enabled endpoints.
    - `enable` string[], required
  - `hostname` string: Optional machine name shown in the dashboard. Control characters are removed.

## Response `200`

Existing credential renewed (same token) or rotated in place (new token); rotated tells which

- OkibiCliCredentialEnvelope
  - `success` unknown, required
  - `created` boolean, required: True when this bootstrap created the installation's credential (HTTP 201).
  - `rotated` boolean, required: True when a new registration token replaced the existing credential's secret in place (HTTP 200).
  - `account` OkibiLinkedAccount, required: The Locus user behind the Okibi identity link. Locus provisions an account for an Okibi-verified email that has none; that account keeps a managed password until the person sets one through the emailed link or the dashboard's first screen.
    - `email` string, email, required
    - `passwordSetupPending` boolean, required: True while the provisioned account still has to choose a password. Tell the user to check their email for the Locus set-password link.
  - `connection` object, required
    - `id` string, uuid, required
    - `status` 'active' | 'expired' | 'revoked', required
    - `keyPrefix` string, required: Non-secret display prefix.
    - `tools` OkibiCliConnectionTools, required
      - `enable` string[], nullable, required: Provider/endpoint slugs this credential may call. null means every endpoint the workspace has enabled.
    - `expiresAt` string, date-time, required: Moves forward on each authenticated use, to 7 days after that use and never past 30 days after issue.
    - `lastUsedAt` string, date-time, nullable, required
    - `credential` string, required: Raw scoped Locus credential. Capture once and never log it.
  - `storage` object, required
    - `environmentVariable` 'LOCUS_SECRET_KEY', required
    - `instruction` string, required

## Other responses

- `201`: New native credential created for this installation
- `400`: Invalid registration token, empty endpoint allowlist, or unknown field
- `401`: Missing, invalid, or expired Locus OAuth access token
- `403`: Missing mcp:execute, or the signed-in account is not an active member of the workspace
- `404`: Unknown provider/endpoint catalog slug
- `409`: The installation's native credential was revoked in the dashboard, or the registration token already belongs to another installation

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)