> ## Documentation Index > Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.checkfu.com. Current wire version: `2026-08-31` (`Checkfu-Version: 2026-08-31`). > Mutating HTTP requests require `Authorization: Bearer $CHECKFU_API_KEY`, `Checkfu-Version: 2026-08-31`, `Content-Type: application/json`, and `Idempotency-Key` on retriable writes. Ordinary API keys are Workspace-bound; do not send a Workspace selector header. > Core workflow: create an Agent (`POST /v1/agents`) and Environment (`POST /v1/environments`), grant `use_environment` (`POST /v1/permission-assignments`), create a Session (`POST /v1/sessions`), send events (`POST /v1/sessions/{id}/events`), stream progress (`GET /v1/sessions/{id}/events/stream`), and read the input result (`GET /v1/sessions/{id}/inputs/{input_id}/result`). > Domain model: an Agent is mutable configuration; a Session freezes its AgentVersion and Environment at creation and owns its private workspace and ordered event history. Vault stores secret credentials; Connection links an external account; ActionApproval records human approval before an action runs. > Capability status combines `audience`, `stability`, `availability`, evaluated prerequisites, and release evidence; check https://docs.checkfu.com/getting-started/status (`GET /v1/support/capabilities`) for live `available` status. # Plan or apply an Agent's access setup > Resolve the exact PermissionAssignments Session admission checks for one Agent, one acting Principal and one Environment under the declared workflow, and… ## OpenAPI ````yaml /openapi.json post /v1/agents/{agent_id}/access/setup openapi: 3.1.0 info: title: Checkfu API version: '2026-08-31' description: >- Authentication is declared per operation: API-key, runtime, or connector bearer; Automation signature; or credential-free pairing redemption. Every general Checkfu REST request requires the dated `Checkfu-Version` header (one of: 2026-08-31); the three MCP JSON-RPC transports use `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth callback carries neither Checkfu header. API keys resolve one Workspace without a request selector; authenticated responses identify it with `Checkfu-Workspace-Id`. servers: - url: https://api.checkfu.com security: - bearerAuth: [] tags: - name: organizations - name: sourceRepositories - name: tenants - name: workspaces - name: principals - name: principalGroups - name: principalAccessCredentials - name: apiKeys - name: agents - name: harnessRuntime - name: permissionAssignments - name: actionPolicies - name: files - name: memoryStores - name: modelCredentials - name: modelRoutingProfiles - name: toolSources - name: skills - name: skillSources - name: skillProposals - name: instructionProposals - name: catalog - name: concepts - name: support - name: connections - name: connectionAssignments - name: connectedRuntimes - name: fileTrees - name: collaboration - name: automationGraphs - name: automations - name: actionApprovals - name: standingApprovals - name: workloadReviewPolicies - name: usage - name: models - name: budgets - name: billing - name: sessions - name: audit - name: sessionExports - name: runs - name: runnerPools - name: transcripts - name: sessionWatches - name: sessionCapsules - name: sessionTrajectories - name: webhookEndpoints - name: integrationGateway - name: environments - name: vaults - name: apiMcp - name: a2a paths: /v1/agents/{agent_id}/access/setup: post: tags: - connectionAssignments summary: Plan or apply an Agent's access setup description: >- Resolve the exact PermissionAssignments Session admission checks for one Agent, one acting Principal and one Environment under the declared `workflow`, and report each as `present`, `missing` (no grant), `blocked` (an existing grant is refused by an ActionPolicy or is outside its time window, so apply refuses before writing) or `created`. Each edge is previewed with the context the launch carries: for `acted_as` the API key named by `launching_api_key_id` (a live key of this Workspace), or the calling key when it is omitted; for `personal` the Principal. `acted_as` (an API key starting Sessions on the Principal's behalf) needs the Principal's `act_as` on the Agent; `personal` (the Principal driving the Agent with its own credential and reading its results) also needs `invoke` and `observe`. Both need the Agent's `use_environment` on the Environment, and `use_harness` on its Workspace HarnessProfile when the Agent's harness resolves to one; a platform catalog harness needs none. `dry_run=true` writes nothing. Apply creates only the missing edges, adopts every edge current authority already allows, and never changes another Agent, a Connection selection or an Agent version: launch the returned `agent_version`. `agent_version` must equal the Agent head. Creating grants needs grant-management authority; without it apply refuses before writing. Apply re-checks each grant it creates, because an ActionPolicy matches only once a grant exists: one a policy still refuses is reported `blocked` with its `permission_assignment_id`. After a temporary failure, retrying with the same Idempotency-Key recovers the grants already created and finishes; a refusal after some grants were created names them, and they remain. A retry refused because the Agent, Principal or Environment changed also names them; a new plan then reports them as `present`. A completed replay returns the original result and never re-creates a grant deleted since. Connection and tool access stays with `connections.applyConnectionAccess`. Requires an Idempotency-Key. Checkfu support posture: alpha; hosted. Required evidence journey: connection-lifecycle. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities. operationId: connectionAssignments.setupAgentAccess parameters: - name: agent_id in: path schema: $ref: '#/components/schemas/AgentId' required: true - name: checkfu-version in: header schema: type: string enum: - '2026-08-31' required: true - name: idempotency-key in: header schema: type: string minLength: 1 maxLength: 255 required: true - name: dry_run in: query schema: type: string enum: - 'true' - 'false' required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/SetupAgentAccess' required: true responses: '200': description: AgentAccessSetupResult content: application/json: schema: $ref: '#/components/schemas/AgentAccessSetupResult' headers: checkfu-workspace-id: description: The Workspace resolved from the authenticated bearer credential. required: true schema: $ref: '#/components/schemas/WorkspaceId' '400': description: Typed Checkfu wire error content: application/json: schema: $ref: '#/components/schemas/ValidationMalformedError' '401': description: Typed Checkfu wire error content: application/json: schema: type: object properties: type: type: string enum: - error error: type: object properties: type: type: string enum: - authentication_error code: type: string enum: - auth.invalid_key message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-invalid-key description: >- Stable public documentation and remedy for this error type. required: - type - code - message - more additionalProperties: false request_id: type: string minLength: 1 required: - type - error - request_id additionalProperties: false '403': description: >- The organization, tenant, or workspace backing this key is administratively disabled. | Deployment governance or retention policy denied the request. content: application/json: schema: anyOf: - type: object properties: type: type: string enum: - error error: type: object properties: type: type: string enum: - permission_error code: type: string enum: - auth.disabled_tenancy message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-disabled-tenancy description: >- Stable public documentation and remedy for this error type. required: - type - code - message - more additionalProperties: false request_id: type: string minLength: 1 required: - type - error - request_id additionalProperties: false - $ref: '#/components/schemas/PolicyDeniedError' '404': description: >- The requested resource does not exist in the resolved deployment boundary. content: application/json: schema: $ref: '#/components/schemas/ValidationNotFoundError' '409': description: >- The request conflicts with the resource's current state. | An idempotent mutation conflicts with a completed or in-progress request for the same key. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationConflictError' - $ref: '#/components/schemas/IdempotencyConflictError' '429': description: Typed Checkfu wire error headers: retry-after: description: >- Delay in seconds for rate limits or deployment quotas with a known release or UTC reset boundary required: false schema: type: integer minimum: 1 content: application/json: schema: type: object properties: type: type: string enum: - error error: type: object properties: type: type: string enum: - rate_limit_error code: type: string enum: - budget.exceeded message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#budget-exceeded description: >- Stable public documentation and remedy for this error type. required: - type - code - message - more additionalProperties: false request_id: type: string minLength: 1 required: - type - error - request_id additionalProperties: false '500': description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. content: application/json: schema: $ref: '#/components/schemas/RuntimeInternalError' security: - bearerAuth: [] components: schemas: AgentId: type: string pattern: ^agent_[0-9a-f]{32}$ SetupAgentAccess: type: object properties: agent_version: type: integer maximum: 9007199254740991 exclusiveMinimum: 0 acted_as: $ref: '#/components/schemas/PrincipalId' environment_id: $ref: '#/components/schemas/EnvironmentId' workflow: $ref: '#/components/schemas/AgentAccessWorkflow' launching_api_key_id: $ref: '#/components/schemas/ApiKeyId' required: - agent_version - acted_as - environment_id - workflow additionalProperties: false AgentAccessSetupResult: type: object properties: mode: $ref: '#/components/schemas/AgentAccessSetupMode' agent_id: $ref: '#/components/schemas/AgentId' agent_version: type: integer maximum: 9007199254740991 exclusiveMinimum: 0 acted_as: $ref: '#/components/schemas/PrincipalId' environment_id: $ref: '#/components/schemas/EnvironmentId' workflow: $ref: '#/components/schemas/AgentAccessWorkflow' harness: $ref: '#/components/schemas/AgentAccessHarness' edges: type: array items: $ref: '#/components/schemas/AgentAccessEdge' required: - mode - agent_id - agent_version - acted_as - environment_id - workflow - harness - edges additionalProperties: false WorkspaceId: type: string pattern: ^wrkspc_[0-9a-f]{32}$ ValidationMalformedError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-malformed description: Stable public documentation and remedy for this error type. code: type: string enum: - validation.malformed required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: >- The request could not be decoded or violated a declared input constraint. PolicyDeniedError: type: object properties: error: type: object properties: type: type: string enum: - permission_error message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#policy-denied description: Stable public documentation and remedy for this error type. code: type: string enum: - policy.denied required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: Deployment governance or retention policy denied the request. ValidationNotFoundError: type: object properties: error: type: object properties: type: type: string enum: - not_found_error message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-not-found description: Stable public documentation and remedy for this error type. code: type: string enum: - validation.not_found required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: >- The requested resource does not exist in the resolved deployment boundary. ValidationConflictError: type: object properties: error: type: object properties: type: type: string enum: - conflict_error message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-conflict description: Stable public documentation and remedy for this error type. code: type: string enum: - validation.conflict required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: The request conflicts with the resource's current state. IdempotencyConflictError: anyOf: - $ref: '#/components/schemas/ValidationIdempotencyConflictError' - $ref: '#/components/schemas/ValidationIdempotencyInProgressError' description: >- An idempotent mutation conflicts with a completed or in-progress request for the same key. RuntimeInternalError: type: object properties: error: type: object properties: type: type: string enum: - api_error message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#runtime-internal description: Stable public documentation and remedy for this error type. code: type: string enum: - runtime.internal required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. PrincipalId: type: string pattern: ^prin_[0-9a-f]{32}$ EnvironmentId: type: string pattern: ^env_[0-9a-f]{32}$ AgentAccessWorkflow: type: string enum: - acted_as - personal ApiKeyId: type: string pattern: ^akey_[0-9a-f]{32}$ AgentAccessSetupMode: type: string enum: - plan - applied AgentAccessHarness: anyOf: - $ref: '#/components/schemas/AgentAccessPlatformHarness' - $ref: '#/components/schemas/AgentAccessWorkspaceHarness' AgentAccessEdge: type: object properties: requirement: $ref: '#/components/schemas/AgentAccessRequirement' subject: $ref: '#/components/schemas/Union_123' resource: $ref: '#/components/schemas/Objects_45' permission: $ref: '#/components/schemas/AgentAccessRequirement' status: $ref: '#/components/schemas/AgentAccessEdgeStatus' permission_assignment_id: anyOf: - $ref: '#/components/schemas/PermissionAssignmentId' - type: 'null' required: - requirement - subject - resource - permission - status - permission_assignment_id additionalProperties: false ValidationIdempotencyConflictError: type: object properties: error: type: object properties: type: type: string enum: - conflict_error message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-conflict description: Stable public documentation and remedy for this error type. code: type: string enum: - validation.idempotency_conflict required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: The Idempotency-Key is already bound to a different request. ValidationIdempotencyInProgressError: type: object properties: error: type: object properties: type: type: string enum: - conflict_error message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress description: Stable public documentation and remedy for this error type. code: type: string enum: - validation.idempotency_in_progress required: - type - message - more - code additionalProperties: false type: type: string enum: - error request_id: type: string minLength: 1 required: - error - type - request_id additionalProperties: false description: >- An identical idempotent request is still in progress and may be retried later. AgentAccessPlatformHarness: type: object properties: kind: type: string enum: - platform required: - kind additionalProperties: false AgentAccessWorkspaceHarness: type: object properties: kind: type: string enum: - workspace_profile harness_profile_id: $ref: '#/components/schemas/HarnessProfileId' required: - kind - harness_profile_id additionalProperties: false AgentAccessRequirement: type: string enum: - act_as - invoke - observe - use_environment - use_harness Union_123: anyOf: - type: object properties: type: type: string enum: - principal id: $ref: '#/components/schemas/PrincipalId' required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - group id: $ref: '#/components/schemas/PrincipalGroupId' required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - agent id: $ref: '#/components/schemas/AgentId' required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - agent_placement id: $ref: '#/components/schemas/AgentPlacementId' required: - type - id additionalProperties: false - type: object properties: type: type: string enum: - session id: $ref: '#/components/schemas/SessionId' required: - type - id additionalProperties: false Objects_45: type: object properties: type: $ref: '#/components/schemas/Union_124' id: type: string minLength: 1 required: - type - id additionalProperties: false AgentAccessEdgeStatus: type: string enum: - present - missing - blocked - created PermissionAssignmentId: type: string pattern: ^perm_[0-9a-f]{32}$ HarnessProfileId: type: string pattern: ^hprof_[0-9a-f]{32}$ PrincipalGroupId: type: string pattern: ^pgrp_[0-9a-f]{32}$ AgentPlacementId: type: string pattern: ^aplace_[0-9a-f]{32}$ SessionId: type: string pattern: ^sess_[0-9a-f]{32}$ Union_124: type: string enum: - workspace - agent - connection - tool_source - skill - memory_store - model_binding - harness - environment - computer - agent_placement - principal - automation securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.