> ## 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. # Create a scoped Agent Connection > Creates a short-lived, least-privilege lcac_ credential for MCP and wrapped execution. A secret key may automate this route only when its stored scopes include credentials:manage. Human callers must be the workspace owner with fresh MFA/passkey step-up. ## OpenAPI ````yaml /api-reference/openapi.json post /credits/agent-connections openapi: 3.1.0 info: title: Locus Pro API description: >- Production is live at https://api.paywithlocus.com/api. Stage remains available for evaluation and integration testing at https://api.stage.paywithlocus.com/api; credentials, balances, and tenant data are isolated by environment. Embedded prepaid credits over the Locus pay-per-use catalog. Money and top-up amounts use exact decimal strings (up to 6dp). Every burn requires an Idempotency-Key header. Management routes accept a tenant secret key or authorized dashboard session as shown per operation. Widget routes accept an end-user JWT alone; when a publishable key is present it must belong to the JWT's tenant. MCP uses OAuth 2.1 Authorization Code with PKCE by default and also accepts the explicitly documented tenant secret key, end-user JWT, or scoped agent connection compatibility credentials. Burns accept the execution credentials shown per operation. Publishable keys never authorize management or burns by themselves. version: 0.6.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: >- Available when enabled for the workspace. Enterprise BYOK providers and schema-backed custom actions - name: End users description: End-user accounts, tokens, and allocations - 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: Travel routing description: >- Available when enabled for the workspace. Multi-provider flight search, no-dispatch planning, and feedback - name: MCP description: Stateless Streamable HTTP transport and MCP tool-result contracts - name: Okibi Identity description: >- Available when enabled for the workspace. 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: Agent connections description: Scoped, expiring, revocable credentials for agent execution - name: Capability routing description: Outcome-level web search and research across eligible catalog providers paths: /credits/agent-connections: post: tags: - Authentication - MCP summary: Create a scoped Agent Connection description: >- Creates a short-lived, least-privilege lcac_ credential for MCP and wrapped execution. A secret key may automate this route only when its stored scopes include credentials:manage. Human callers must be the workspace owner with fresh MFA/passkey step-up. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentConnectionCreateRequest' responses: '201': description: Connection created; credential is returned once content: application/json: schema: $ref: '#/components/schemas/AgentConnectionEnvelope' '400': description: Invalid identity, endpoint, expiry, or exact-credit scope '401': $ref: '#/components/responses/UnauthorizedManagement' '403': $ref: '#/components/responses/InsufficientScope' security: - dashboardSession: [] - secretKey: [] components: schemas: AgentConnectionCreateRequest: type: object additionalProperties: false required: - name - mode properties: name: type: string minLength: 1 maxLength: 100 mode: type: string enum: - platform - end_user externalUserId: $ref: '#/components/schemas/ExternalUserId' tools: type: object additionalProperties: false properties: enable: type: array maxItems: 1000 items: type: string pattern: ^[^/]+/[^/]+$ uniqueItems: true pricing: $ref: '#/components/schemas/CredentialPricingPolicy' maxCreditsPerCall: $ref: '#/components/schemas/DecimalString' maxCreditsPerLoop: $ref: '#/components/schemas/DecimalString' expiresInSeconds: type: integer minimum: 300 maximum: 31536000 AgentConnectionEnvelope: type: object additionalProperties: false required: - success - connection properties: success: const: true connection: $ref: '#/components/schemas/AgentConnection' ExternalUserId: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$ description: >- Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address. CredentialPricingPolicy: type: object additionalProperties: false properties: markupBps: type: integer minimum: 0 maximum: 10000 flatMarkupUsdc: $ref: '#/components/schemas/DecimalString' endpoints: type: object maxProperties: 1000 additionalProperties: $ref: '#/components/schemas/CredentialPriceOverride' minProperties: 1 DecimalString: type: string pattern: ^\d+(?:\.\d{1,6})?$ description: >- Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply. AgentConnection: type: object required: - id - name - status - mode - keyPrefix - expiresAt - createdAt - updatedAt - mcp properties: id: type: string format: uuid name: type: string status: type: string enum: - active - expired - revoked mode: type: string enum: - platform - end_user externalUserId: oneOf: - $ref: '#/components/schemas/ExternalUserId' - type: 'null' tools: type: object properties: enable: type: - array - 'null' items: type: string pricing: oneOf: - $ref: '#/components/schemas/CredentialPricingPolicy' - type: 'null' maxCreditsPerCall: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' maxCreditsPerLoop: oneOf: - $ref: '#/components/schemas/DecimalString' - type: 'null' keyPrefix: type: string expiresAt: type: string format: date-time revokedAt: type: - string - 'null' format: date-time rotatedAt: type: - string - 'null' format: date-time lastUsedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time mcp: type: object required: - url properties: url: type: string format: uri headers: type: object additionalProperties: type: string credential: type: string description: Present only in create/rotate responses and shown once InsufficientScopeError: type: object additionalProperties: false required: - success - error - code - message - requiredScopes - presentScopes properties: success: const: false error: const: Forbidden code: const: INSUFFICIENT_SCOPE message: type: string requiredScopes: type: array items: $ref: '#/components/schemas/CreditsTenantScope' minItems: 1 uniqueItems: true presentScopes: type: array items: $ref: '#/components/schemas/CreditsTenantScope' uniqueItems: true CredentialPriceOverride: type: object additionalProperties: false properties: markupBps: type: integer minimum: 0 maximum: 10000 flatMarkupUsdc: $ref: '#/components/schemas/DecimalString' minProperties: 1 CreditsTenantScope: type: string enum: - tenant:read - tenant:write - catalog:write - credits:move - credentials:manage - tokens:manage - payouts:manage - members:manage - widget:read responses: UnauthorizedManagement: description: Missing, invalid, expired, or revoked management credential InsufficientScope: description: >- The authenticated management credential lacks one or more required scopes content: application/json: schema: $ref: '#/components/schemas/InsufficientScopeError' securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. dashboardSession: type: http scheme: bearer description: Locus Pro dashboard session (Cognito). ````