---
title: "Bootstrap a scoped Locus CLI credential from Okibi Identity"
method: POST
path: "/credits/okibi/cli-credential"
tags: ["Okibi Identity"]
---

# Bootstrap a scoped Locus CLI credential from Okibi Identity

`POST /credits/okibi/cli-credential`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/okibi/cli-credential`
- Auth: HTTP bearer

Exchanges a verified Okibi identity grant for one Locus lcac_ execution credential bound to the Okibi identity, CLI installation, and selected workspace. The credential expires 7 days after its last use and never later than 30 days after issue; every bootstrap issues it fresh for 7 days. Generate registrationToken locally from exactly 24 random bytes encoded as unpadded base64url. Replaying the token renews the installation's credential unchanged; a new token rotates that credential in place (same connection, new secret and prefix). A revoked credential is never renewed or rotated. When tools is present the server enables exactly those catalog slugs and restricts the credential to them; when it is omitted the credential may use every endpoint the workspace has enabled, and a fresh bootstrap may replace or lift an existing allowlist. The token is never stored; Locus stores only the derived credential hash.

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

## 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, expired, or inactive Okibi capability
- `403`: Missing mcp:read/mcp:execute or inactive Locus membership
- `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)