> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Register a credential reference in a vault > Registers one credential in a vault and returns the stored reference. Supply exactly one of secret_value (encrypted under the organization's key and stored as ciphertext) or secret_ref (material you already stored yourself) for secret-backed kinds. Integration grants carry neither; they reference a connected account that mints short-lived credentials. Secret material is never echoed back on this or any later response. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/vaults/{vault_id}/credentials openapi: 3.1.0 info: title: Managed Agents API version: 0.13.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/vaults/{vault_id}/credentials: post: tags: - Vaults summary: Register a credential reference in a vault description: >- Registers one credential in a vault and returns the stored reference. Supply exactly one of secret_value (encrypted under the organization's key and stored as ciphertext) or secret_ref (material you already stored yourself) for secret-backed kinds. Integration grants carry neither; they reference a connected account that mints short-lived credentials. Secret material is never echoed back on this or any later response. operationId: managedAgentsCreateVaultCredential parameters: - description: Vault id (UUID) as returned by createVault or listVaults. in: path name: vault_id required: true schema: description: Vault id (UUID) as returned by createVault or listVaults. format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsCreateVaultCredentialRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsVaultCredential' description: >- One credential in a vault, described without its secret value — no field on this shape can carry secret material, which is what makes it safe to list over the API. Returned when managing a vault's contents; the value itself is opened only inside a running session. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '409': description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '429': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '500': description: An unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsCreateVaultCredentialRequest: description: >- Request body for adding one credential to a vault. Its shape depends on credential_type. bearer_token and env_var accept exactly one of secret_value or secret_ref; webhook_secret requires secret_value; integration accepts neither. Secret material is encrypted at rest and never returned. properties: allowed_hosts: description: >- Hosts the credential may be sent to under limited networking. Supports wildcards such as *.example.com. items: type: string type: array credential_type: description: >- bearer_token authenticates to an MCP server and requires mcp_server_url. env_var is exposed to the sandbox for CLIs and SDKs. webhook_secret never reaches the sandbox and is used only to verify inbound webhook signatures. integration references a connected provider account and carries no secret of its own. enum: - bearer_token - env_var - webhook_secret - integration type: string display_name: description: Operator-facing label. type: string injection_locations: description: >- Where a bearer or MCP credential attaches to a request. Defaults to headers, which is recommended unless the service reads the secret from the request body. Ignored for env_var, which is injected into the sandbox environment instead, and for integration. items: $ref: '#/components/schemas/ManagedAgentsInjectionLocation' type: array integration_connection_id: description: >- The connected account this grant uses. Required for the integration kind. type: string integration_permission: description: >- Provider permission preset applied when minting. See the provider's list; defaults to the least-privileged one. type: string integration_resources: description: >- Resources within the connection this grant may reach, e.g. GitHub repository names. Empty means every resource the connection reaches, which is broader than most grants should be. items: type: string type: array labelbox_scope: $ref: '#/components/schemas/ManagedAgentsLabelboxScopeRequest' description: >- Labelbox product-state authorization ceiling: either exact projects or organization-wide access, optionally restricted to one exact Slack audience with an explicit internal or Slack Connect classification. Required when credential_type is bearer_token and mcp_server_url is that service; rejected for any other server. mcp_server_url: description: >- The MCP server this credential unlocks. Must be http or https and must not embed credentials. Required for the MCP kinds and immutable afterwards, so it is validated here rather than at the first connection. type: string metadata: additionalProperties: {} description: >- Free-form caller-owned JSON stored with the credential row and returned on reads. Not interpreted by the service; never put secret material here, since unlike secret_value it is returned verbatim. The key labelbox_scope is reserved for the typed field. type: object network_mode: description: >- Where the credential may be sent. Defaults to limited, which restricts it to allowed_hosts. enum: - limited - unrestricted type: string secret_name: description: >- Environment variable or header name the secret binds to inside the sandbox. Required for env_var. type: string secret_ref: description: >- Reference to material stored outside this service, carrying a provider prefix. Not supported for webhook_secret, which this service verifies itself. Requests carrying obvious inline secret material are rejected. type: string secret_value: description: >- The credential material itself. Encrypted at rest and never returned or logged by this service. Supply this or secret_ref, not both. type: string required: - credential_type type: object example: allowed_hosts: - example credential_type: bearer_token display_name: example-name injection_locations: - headers integration_connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d integration_permission: example integration_resources: - example labelbox_scope: mode: projects project_ids: - project-id mcp_server_url: https://example.com metadata: key: example network_mode: limited secret_name: example secret_ref: example secret_value: example ManagedAgentsVaultCredential: description: >- One credential in a vault, described without its secret value — no field on this shape can carry secret material, which is what makes it safe to list over the API. Returned when managing a vault's contents; the value itself is opened only inside a running session. properties: allowed_hosts: description: >- Hosts the credential may be sent to when network_mode is limited. Ignored under unrestricted. items: type: string type: array created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string credential_id: description: >- Identifier for this credential (UUID). Server-assigned, and unique only within its vault. type: string credential_type: description: >- How the credential is used: bearer_token, env_var, or webhook_secret. Legacy rows may report mcp_oauth or integration, so this remains a string rather than a closed response enum. type: string display_name: description: >- Operator-facing label for the credential. Optional: a credential is identifiable by its secret_name or MCP server without one. type: string injection_locations: description: >- Where the credential is attached to an outbound request: headers, body, or both. Headers alone is recommended; a secret in a request body is far easier to log by accident. Meaningful only for the MCP OAuth and bearer-token kinds: env_var is injected into the sandbox environment, and integration mints its own token per session. items: type: string type: array integration_connection_id: description: >- Organization integration connection this credential grants a session (UUID). Set only for the integration kind, where it replaces sealed material: the provider mints a short-lived token per session. type: string integration_permission: description: >- Permission preset applied when a token is minted for this grant; see the provider's scope table. An unknown value is rejected on write rather than at mint time. type: string integration_resources: description: >- Resources within the connection the grant is narrowed to — repositories, for GitHub. Empty means every resource the connection itself can reach, which is broader than most grants should be. items: type: string type: array labelbox_scope: $ref: '#/components/schemas/ManagedAgentsLabelboxToolsScope' description: >- Labelbox product-state authorization ceiling: either exact projects or organization-wide access, optionally restricted to one exact Slack audience with an explicit internal or Slack Connect classification. Required for a bearer_token credential whose mcp_server_url is that service; rejected for any other server. Replaced as a whole on update and kept when omitted. mcp_server_url: description: >- MCP server this credential may be sent to. Required for bearer_token and immutable afterwards, so a stored secret cannot be repointed at a different service. type: string metadata: additionalProperties: {} description: >- Free-form caller-supplied key/value labels. Stored verbatim and never interpreted by the service. The key labelbox_scope is reserved for the typed field of that name. type: object network_mode: description: >- How far the credential may travel: limited confines it to allowed_hosts, unrestricted permits any host. limited is the safe default. enum: - limited - unrestricted type: string organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string platform_mcp_service: description: >- Deployment-derived identity of the exact platform MCP service this credential targets. Present as slack_tools only when mcp_server_url matches the configured Slack tools endpoint; never caller-controlled or stored. enum: - slack_tools type: string secret_name: description: >- Environment variable or header name the secret binds to inside the sandbox. Required for the env_var kind. type: string secret_ref: description: >- Pointer to material stored in an external secret manager, carrying a provider prefix such as kms: or vault:. Opaque to this service, and empty on the normal path where the value is sealed into the credential itself. type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string vault_id: description: Vault this credential belongs to (UUID). type: string required: - organization_id - vault_id - credential_id - credential_type - created_at - updated_at type: object example: allowed_hosts: - example created_at: '2026-02-18T09:30:00.000Z' credential_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d credential_type: example display_name: example-name injection_locations: - example integration_connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d integration_permission: example integration_resources: - example labelbox_scope: mode: projects organization_id: organization-id project_ids: - project-id mcp_server_url: https://example.com metadata: key: example network_mode: limited organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d platform_mcp_service: slack_tools secret_name: example secret_ref: example updated_at: '2026-02-18T09:30:00.000Z' vault_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsApiError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - analytics - analytics_not_ready - artifact_fetch_unavailable - artifact_generation_mismatch - artifact_hash_mismatch - artifact_invalid_events - artifact_invalid_json - artifact_not_allowlisted - artifact_size_mismatch - atlassian_rate_limited - atlassian_unavailable - atomic_ingest_timeout - auth_unavailable - automation_event_source_invalid - automation_memory_unavailable - automation_reference_invalid - automation_runs_unconfigured - automations_unconfigured - bad_gateway - built_in_catalog_unavailable - built_in_integrations_disabled - built_in_integrations_unconfigured - compute_offerings_unavailable - conflict - content_store_request_canceled - content_store_unavailable - content_store_upload_timeout - credential_encryption_unconfigured - delegate_preparation_failed - entity_family_not_permitted - environment_not_verified - evaluation_cancellation_pending - evaluation_deletion_pending - event_admission_unavailable - event_ingress_unavailable - event_source_verification_credential_invalid - event_sources_unconfigured - execution_unconfigured - file_quota_exceeded - file_storage_unconfigured - forbidden - gateway_timeout - gestalt_unconfigured - github_rate_limited - github_unavailable - handoff_access_invalid - handoff_access_unavailable - handoff_access_unsupported - handoff_capture_unavailable - handoff_requires_retest - handoff_revoke_unavailable - handoff_signal_unavailable - idempotency_conflict - idempotency_in_progress - idempotency_unavailable - ingest_policy_changed - ingest_policy_not_found - ingest_policy_revoked - integrations_unconfigured - internal_error - invalid_json - invalid_pull_request_review_result - invalid_request - invalid_scope - invariant_violation - launchdarkly_rate_limited - launchdarkly_unavailable - live_fleet_unconfigured - managed_agents_unavailable - merge_key_rejected - merge_link_unavailable - merge_rate_limited - merge_unavailable - missing_dependency - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - mutation_transaction_budget_exceeded - not_found - page_token_expired - payload_too_large - persistence_busy - precondition_failed - precondition_required - provider_registration_unsupported - provider_selection_unsupported - rate_limit_exceeded - rate_limited - repository_automation_unconfigured - request_too_large - reserved_source_type - revision_conflict - run_log_store_unavailable - runner_image_resolution_failed - sandbox_provider_disabled - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_unavailable - session_start_not_admitted - setup_fallback_environment_unsafe - setup_run_finished - setup_run_in_progress - setup_run_limit - setup_run_not_started - setup_runs_unavailable - skill_storage_unconfigured - slack_channels_rejected - slack_channels_unavailable - slack_channels_unconfigured - slack_connection_malformed - slack_event_intake_unavailable - slack_installation_mismatch - slack_missing_scope - slack_rate_limited - slack_reapproval_required - source_ownership_mismatch - source_revision_conflict - spanner_unavailable - streaming_unsupported - submission_transaction_budget_exceeded - task_version_number_conflict - team_board_unconfigured - too_many_streams - unauthorized - unsupported_media_type - vault_creation_retired - version_content_conflict - webhook_delivery_too_large - workspace_boundary_denied message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsInjectionLocation: description: >- One place a credential is applied to an outbound request. Headers alone is recommended; a secret in a request body is far easier to log by accident. enum: - headers - body type: string example: headers ManagedAgentsLabelboxScopeRequest: description: >- Labelbox product-state authorization ceiling. Projects mode permits one exact project set. Organization mode permits organization-wide access, optionally pinned to one exact Slack binding whose internal or Slack Connect classification is explicit. The organization always equals the credential's owner. examples: - mode: projects project_ids: - project-id properties: audience: $ref: '#/components/schemas/ManagedAgentsLabelboxAudienceRequest' description: >- Optional in organization mode: pins the credential to one exact Slack binding audience classified as internal or Slack Connect; without it the scope follows the vault wherever the vault is granted. Forbidden in projects mode. mode: description: Scope mode. Omit for the backward-compatible projects mode. enum: - projects - organization type: string organization_id: description: >- Labelbox organization the projects belong to. Optional: filled in from the organization that owns the credential, and rejected if it names any other. type: string project_ids: description: >- Projects mode requires exactly 1 to 100 project ids. Forbidden in organization mode. items: type: string maxItems: 100 minItems: 1 type: array uniqueItems: true type: object example: mode: projects project_ids: - project-id ManagedAgentsLabelboxToolsScope: description: >- Labelbox product-state authorization ceiling. The organization always equals the credential's owner. Projects mode permits one exact project set; organization mode permits organization-wide reads only from one exact Slack binding whose internal or Slack Connect classification is explicit. examples: - mode: projects organization_id: organization-id project_ids: - project-id properties: audience: $ref: '#/components/schemas/ManagedAgentsLabelboxToolsAudience' description: >- Optional organization-mode audience: pins the credential to one exact Slack binding and its internal-or-Slack-Connect classification; without it the scope follows the vault wherever the vault is granted. Forbidden in projects mode. mode: description: Scope mode. Omitted legacy values are canonicalized to projects. enum: - projects - organization type: string organization_id: description: >- Labelbox organization the projects belong to. Must equal the organization that owns the credential; filled in from it when omitted on write. type: string project_ids: description: >- Projects-mode ceiling: exactly 1 to 100 project ids, each up to 128 characters of letters, digits, hyphen, or underscore. Forbidden in organization mode; validated as unique and sorted on write. items: type: string maxItems: 100 minItems: 1 type: array uniqueItems: true required: - organization_id type: object example: mode: projects organization_id: organization-id project_ids: - project-id ManagedAgentsLabelboxAudienceRequest: description: >- Exact Slack trigger binding authorized to use an organization-wide Labelbox product-state credential, with an explicit internal or Slack Connect classification. properties: binding_id: description: Exact Slack trigger binding id authorized to use the credential. type: string channel_id: description: >- Exact Slack channel id used by the binding. The signed webhook receipt's sharing classification must match kind. type: string connection_id: description: Exact Slack integration connection id used by the binding. type: string kind: description: >- Optional restriction of organization-wide Labelbox access to one exact binding whose internal or Slack Connect classification is explicit. enum: - internal_slack_binding - slack_connect_binding type: string required: - kind - binding_id - connection_id - channel_id type: object example: binding_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d channel_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d kind: internal_slack_binding ManagedAgentsLabelboxToolsAudience: description: >- Exact Slack trigger binding authorized to use an organization-wide Labelbox product-state credential, with an explicit internal or Slack Connect classification. properties: binding_id: description: Exact Slack trigger binding id authorized to use this credential. type: string channel_id: description: >- Exact Slack channel id used by the binding. The signed webhook receipt's sharing classification must match kind. type: string connection_id: description: Exact Slack integration connection id used by the binding. type: string kind: description: >- Trusted session audience kind. internal_slack_binding requires a non-shared channel; slack_connect_binding is an explicit opt-in to one externally shared channel. enum: - internal_slack_binding - slack_connect_binding type: string required: - kind - binding_id - connection_id - channel_id type: object example: binding_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d channel_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d connection_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d kind: internal_slack_binding securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````