> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com. > Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt. # Exchange a Locus OAuth token for a scoped CLI credential > 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 ()" in the dashboard. ## OpenAPI ````yaml /api-reference/openapi.json post /credits/cli/credential openapi: 3.1.0 info: title: Locus Pro API description: >- Access paid tools, manage prepaid balances, and build usage billing. Send money as exact decimal strings and reuse Idempotency-Key on retries. Management routes require a scoped server key or authorized dashboard session. Sensitive workspace changes require an owner or admin with recent MFA or passkey verification, except where an operation documents a stricter boundary. Interactive agents use MCP OAuth; unattended agents use scoped Agent Connections. Browser widgets use end-user tokens. version: 0.7.0 servers: - url: https://api.paywithlocus.com/api description: Production - url: https://api.stage.paywithlocus.com/api description: Stage — evaluation and integration testing security: - secretKey: [] tags: - name: Authentication description: Email-verified self-serve account creation and dashboard identity - name: Tenants description: Tenant profile, keys, and settings (dashboard session or secret key) - name: Workspace members description: Invite-only human workspace membership and role administration - name: Catalog description: Enable/disable APIs and set markups - name: Custom APIs description: Feature-gated enterprise BYOK providers and schema-backed custom actions - name: End users description: End-user accounts, tokens, and allocations - name: Customers description: >- Names for the customers a tenant attributes spend to, and every customer's spend - name: Top-ups description: Locus-hosted checkout top-ups and quotes - name: Ledger description: Burn/top-up history and earnings - name: Webhooks description: Signed events, delivery inspection, and replay - name: Burn description: Metered pay-per-use calls - name: MCP description: Stateless Streamable HTTP transport and MCP tool-result contracts - name: Okibi Identity description: >- Feature-gated Okibi identity verification and scoped native CLI credential bootstrap - name: Widget description: End-user JWT surface; a matching publishable key is optional - name: Agent-native onboarding description: >- Self-registration, human Stripe funding handoff, and restricted account setup for headless agents - name: Hosted Workflows description: >- Tenant-private TypeScript Workflow definitions, immutable versions, bounded runs, artifacts, and recovery - name: Resources description: >- Durable resources an agent bought, such as phone numbers, inboxes and sandboxes - name: Tasks description: >- Delegate a multi-step outcome to Locus with one goal string. Locus compiles an acceptance contract, discovers and calls enabled catalog capabilities with the caller's own credits and spending controls, checks every returned value against stored provider evidence, and returns structured results, files, requirement statuses, and settled cost. Enabled when the deployment sets LOCUS_TASKS_ENABLED. - name: Agent connections description: Scoped, expiring, revocable credentials for agent execution - name: Recipes description: >- Search, research, extraction, enrichment, and travel outcomes across providers paths: /credits/cli/credential: post: tags: - Authentication summary: Exchange a Locus OAuth token for a scoped CLI credential description: >- 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 ()" in the dashboard. operationId: postCreditsCliCredential requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - registrationToken properties: registrationToken: $ref: '#/components/schemas/AgentRegistrationToken' tools: type: object additionalProperties: false required: - enable description: >- Optional endpoint allowlist. Omit it to leave the credential unrestricted within the workspace's enabled endpoints. properties: enable: type: array minItems: 1 maxItems: 200 uniqueItems: true items: type: string pattern: ^[^/\s]+/[^/\s]+$ description: >- Exact provider/endpoint catalog slug, for example apollo/people-search. hostname: type: string minLength: 1 maxLength: 64 description: >- Optional machine name shown in the dashboard. Control characters are removed. responses: '200': description: >- Existing credential renewed (same token) or rotated in place (new token); rotated tells which content: application/json: schema: $ref: '#/components/schemas/OkibiCliCredentialEnvelope' '201': description: New native credential created for this installation content: application/json: schema: $ref: '#/components/schemas/OkibiCliCredentialEnvelope' '400': description: >- Invalid registration token, empty endpoint allowlist, or unknown field '401': description: Missing, invalid, or expired Locus OAuth access token '403': description: >- Missing mcp:execute, or the signed-in account is not an active member of the workspace '404': description: Unknown provider/endpoint catalog slug '409': description: >- The installation's native credential was revoked in the dashboard, or the registration token already belongs to another installation security: - mcpOAuth: - mcp:read - mcp:execute components: schemas: AgentRegistrationToken: type: string pattern: ^[A-Za-z0-9_-]{32}$ description: >- Canonical base64url encoding of 24 bytes generated by a cryptographically secure random-number generator. OkibiCliCredentialEnvelope: type: object additionalProperties: false required: - success - created - rotated - account - connection - storage properties: success: const: true created: type: boolean description: >- True when this bootstrap created the installation's credential (HTTP 201). rotated: type: boolean description: >- True when a new registration token replaced the existing credential's secret in place (HTTP 200). account: $ref: '#/components/schemas/OkibiLinkedAccount' connection: type: object additionalProperties: false required: - id - status - keyPrefix - tools - expiresAt - lastUsedAt - credential properties: id: type: string format: uuid status: type: string enum: - active - expired - revoked keyPrefix: type: string description: Non-secret display prefix. tools: $ref: '#/components/schemas/OkibiCliConnectionTools' expiresAt: type: string format: date-time description: >- Moves forward on each authenticated use, to 7 days after that use and never past 30 days after issue. lastUsedAt: oneOf: - type: string format: date-time - type: 'null' credential: type: string pattern: ^lcac_ readOnly: true description: Raw scoped Locus credential. Capture once and never log it. storage: type: object additionalProperties: false required: - environmentVariable - instruction properties: environmentVariable: const: LOCUS_SECRET_KEY instruction: type: string OkibiLinkedAccount: type: object additionalProperties: false required: - email - passwordSetupPending description: >- 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. properties: email: type: string format: email passwordSetupPending: type: boolean description: >- True while the provisioned account still has to choose a password. Tell the user to check their email for the Locus set-password link. OkibiCliConnectionTools: type: object additionalProperties: false required: - enable properties: enable: oneOf: - type: array items: type: string - type: 'null' description: >- Provider/endpoint slugs this credential may call. null means every endpoint the workspace has enabled. securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. mcpOAuth: type: oauth2 description: >- Primary authentication for the hosted MCP resource. Public clients use Authorization Code with PKCE S256. mcp:read covers discovery and resource reads; billed tools/call additionally requires mcp:execute; offline_access requests a rotating refresh token. flows: authorizationCode: authorizationUrl: https://api.paywithlocus.com/api/credits/mcp/oauth/authorize tokenUrl: https://api.paywithlocus.com/api/credits/mcp/oauth/token refreshUrl: https://api.paywithlocus.com/api/credits/mcp/oauth/token scopes: mcp:read: Discover and read the authenticated MCP catalog and resources. mcp:execute: Execute billed MCP tools. offline_access: Issue and rotate a persistent refresh token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.