---
title: "Claim Workspace Integration"
method: POST
path: "/workspaces/{workspace_id}/integrations/claim"
tags: ["WorkspaceIntegration"]
---

# Claim Workspace Integration

`POST /workspaces/{workspace_id}/integrations/claim`

Claim a claimable Workspace Integration (e.g. GitHub)

## Path parameters

- `workspace_id` string, required

## Request body

- WorkspaceIntegrationClaimRequest
  - `integration_type` 'slack' | 'github_app' | 'jira' | 'atlassian_connect' | 'export_feed_google_bigquery' | 'export_feed_google_cloud_storage' | 'export_feed_google_pubsub' | 'segment', required — Integration type
  - `installation_id` string — installation id for this specific app installation
  - `github_installation_id` integer — deprecated GitHub identifier for this specific app installation

## Response `201`

Claimed Workspace Integration

- WorkspaceIntegration
  - `id` string — unique identifier
  - `name` string — Human-friendly integration descriptor
  - `integration_type` 'atlassian_connect' | 'atlassian_rovo' | 'export_feed_google_bigquery' | 'export_feed_google_cloud_storage' | 'export_feed_google_pubsub' | 'github_app' | 'jira' | 'jira_server_plugin' | 'microsoft_teams_webhook' | 'segment' | 'slack' | 'xray' | 'xray_sync'
  - `integration_categories` string[]
  - `installation_id` string — a unique id that identifies this integration in the third party service, if applicable
  - `claim_expiration_seconds` integer — length of time until this integration expires, if left unclaimed. Leaving this empty means there is no expiry.
  - `workspace_id` string — Associated workspace
  - `enabled` boolean — Disable to stop running integration
  - `authentication` object — Optional integration authentication information
    - `oauth_token_id` string — Optional OAuth token id, if used by integration
    - `user_id` string — Optional associated mabl user identifier
    - `username` string — Optional username in the 3rd party integration
    - `api_key` string — Optional API key to use for auth in the integration
    - `client_id` string — Optional client id to use for auth in the integration
    - `client_secret` string — Optional client secret to use for auth in the integration
    - `jwt` string — Optional JWT token to use for auth in the integration
  - `encrypted_store` string — Encryption store to use for sensitive data
  - `status` 'success' | 'error' | 'pending' — Last known integration state
  - `statistics` object — Optional integration operational statistics
    - `last_write_operation_time` integer — UTC epoch millisecond time of last write
    - `last_read_operation_time` integer — UTC epoch millisecond time of last read
    - `write_operation_count` integer — Approximate number of write operations
    - `read_operation_count` integer — Approximate number of read operations
  - `config` object — Extensible integration specific configurations
    - `slack` object — Slack resource configuration
      - `bot_user_id` string — bot user id (Slack scoped bot unique id) of bot added by integration
      - `channel_id` string — channel id (Slack scoped unique id)
      - `channel_name` string, required — channel name
      - `team_id` string — team id (Slack scoped unique id)
      - `team_name` string — team name
      - `user_id` string — user id (Slack scoped user unique id) of user that added integration
      - `mention_users` SlackUser[] — List of users to mention in the slack message
        - `user_id` string — Slack user ID that will be used in slack API calls
        - `user_name` string — Name of the user
      - `mention_groups` SlackGroup[] — List of groups to mention in the slack message
        - `group_id` string — Slack group ID that will be used in slack API calls
        - `group_name` string — Name of the group
    - `github` object — GitHub resource configuration
      - `github_app_id` integer, required — GitHub app unique identifier (can be different if customer installs/hosts their own webhook)
      - `github_organization_name` string, required — GitHub organization name (variant)
      - `github_organization_id` integer, required — GitHub organization invariant identifier
      - `github_installation_id` integer — GitHub identifier for this specific app installation
      - `create_repository_dispatch_event_for_insight` boolean — Creates a GitHub RepositoryDispatch event from an insight
      - `create_issues_for_insights` boolean — Create a new github issue when an insight is received
      - `create_checks_on_deployment` boolean — Create new github check runs on mabl deployment
      - `allow_manual_check_rerun` boolean — Allow github check runs to be manually re-run
      - `installation_status` 'created' | 'deleted' | 'new_permissions_accepted' — Current app installation status
      - `installation_payload` string — JSON serialized payload of original installion notification (future migrations)
      - `repositories` GithubRepository[] — Repository list
        - `id` integer, required — GitHub invariant repo number
        - `name` string, required — GitHub repo name
        - `html_url` string — URL to GitHub repo HTML page
        - `description` string — Repo description
        - `full_name` string, required — GitHub repo full name
        - `is_public` boolean, required — Is this repository public
      - `default_repository_id` integer — The default github repository id
      - `hook_id` string — GitHub app installation specific webhook id
    - `exclusion_categories` string[] — List of insight categories to exclude
    - `exclusion_buckets` string[] — (slack) Broad buckets of insights excluded. Currently only used in the UI
    - `inclusion_plan_labels` string[] — A list of plan labels this integration applies to
    - `exclusion_statuses` string[] — A list of insight status types to exclude
    - `include_notes` boolean — set to true to send notes to this integration (if supported)
    - `plan_run_events` object — Send notifications for the following plan run events
      - `plan_run_started` boolean — Send notification when plan run starts
      - `plan_run_passed` boolean — Send notification when plan run completes with passing status
      - `plan_run_failed` boolean — Send notification when plan run completes with failed, cancelled or terminated status
      - `plan_run_status_changed` boolean — Send notification when status of plan run changes (e.g. failed to succeeded)
    - `deployment_events` object — Send notifications for the following deployment events
      - `deployment_failed` boolean — Send notification when a deployment completes with a failure analysis
    - `agent_session_events` object — Send notifications for the following cloud agent (test authoring) session outcomes
      - `agent_session_ready_for_review` boolean — Send notification when a cloud agent session completes and its result is ready for review
      - `agent_session_needs_input` boolean — Send notification when a cloud agent session pauses awaiting user input
      - `agent_session_failed` boolean — Send notification when a cloud agent session ends in failure
    - `export` object — Configurations for GCP Big Query delivery resource
      - `gcp_project_name` string — (export_feed_google_bigquery) GCP project name for Big Query delivery
      - `gcp_bigquery_dataset_name` string — (export_feed_google_bigquery) GCP data set for Big Query delivery
      - `gcp_bigquery_table_prefix` string — (export_feed_google_bigquery) GCP table prefix for Big Query delivery
      - `enable_personal_information_redaction` boolean — If enabled, replace email addresses with "PII_REDACTED"
    - `issue_tracker` object — Configuration for an issue tracker integration
      - `base_url` string — Base URL for issue links
      - `schema_ids` string[] — List of issue schema IDs within this integration
      - `project_ids` string[] — List of project ids associated with this integration
      - `schemas` IssueSchema[] — DEPRECATED - List of issue schemas
        - `id` string, required — ID for this schema; guaranteed to be unique within the associated integration
        - `key` IssueSchemaKey[], required — Composite key for the schema, expressed as a list of field ids and values (must be a subset of fields)
          - `field_id` string, required
          - `field_value` unknown, required
        - `fields` IssueSchemaField[], required — All fields in the schema
          - `id` string, required — Field identifier
          - `name` string, required — Human-friendly field descriptor
          - `type` 'project' | 'issuetype' | 'user' | 'priority' | 'text' | 'textarea' | 'labels' | 'number' | 'date' | 'datetime' | 'checkboxes' | 'radiobuttons', required — Field type
          - `allowed_values` unknown[] — Allowed values for the field if applicable
            - unknown
          - `is_required` boolean, required — Whether the field is required
    - `atlassian_connect` object — configuration settings for atlassian connect app
      - `product_type` 'jira' | 'confluence' — The Atlassian product type for this integration
      - `installation_payload` string, required — JSON serialized payload of original installion notification (future migrations)
    - `jira` object — Configurations for a JIRA resource
      - `id` string — CloudID Resource identifier
      - `name` string, required — Resource name
      - `avatarUrl` string — User avatar URL
      - `scopes` string[]
    - `segment` object — Configurations for a segment resource
      - `destination_name` string, required — name of destination to connect to
      - `source_name` string, required — name of source to connect
    - `microsoft_teams_webhook` object — Configurations for a Microsoft Teams Webhook
      - `webhook_url` string, required — The webhook url to publish messages to
      - `card_actions_enabled` boolean — Indicates if actions (like re-run plan) should be part of the published cards
    - `xray` object — Configuration for an Xray export integration
      - `project_key` string, required — The Jira project key where Xray test issues will be created.
      - `test_type` string, required — The test type for Xray test issues that will be created.
    - `xray_sync` object — Configuration for an Xray Synchronization integration
      - `project_key` string — The project key in Jira for the associated Xray instance
      - `project_url` string — The base URL for the Jira project associated with this Xray instance
      - `result_synchronization` object — Configuration for result synchronization
        - `auto_sync_enabled` boolean — Whether automatic synchronization is enabled
        - `auto_create_entities` boolean — Whether to automatically create entities
        - `failed_steps_only` boolean — Whether to synchronize only failed steps
        - `construct_xray_steps` boolean — Whether to construct Xray Steps for synchronization. If false, Evidence will be attached as global Evidence and Xray Steps will not be constructed in the upload.
        - `functional_browser_artifact_types` XrayFunctionalBrowserTestEvidenceArtifactTypeEnum[] — Types of functional browser artifacts to synchronize
        - `functional_api_artifact_types` XrayFunctionalApiTestEvidenceArtifactTypeEnum[] — Types of functional api artifacts to synchronize
        - `functional_mobile_artifact_types` XrayFunctionalMobileTestEvidenceArtifactTypeEnum[] — Types of functional mobile artifacts to synchronize
  - `created_time` integer — Time at which the insight was created
  - `created_by_id` string — The ID of the user who created this insight
  - `last_updated_time` integer — time the insight was last updated
  - `last_updated_by_id` string — The ID of the user who last updated this insight
  - `tags` Tag[] — Tags to bind an integration and child entities (e.g. Plan/Test), if appropriate
    - `name` string, required — tag name
    - `values` string[]

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `409` — Conflict on attempt to reclaim
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)