Cross-workspace sharing ​

The following endpoints enable you to manage cross-workspace grants programmatically.

Grants are two-sided. Outgoing grants are the grants your workspace shares out, and they support full management operations. Incoming grants are the grants other workspaces share with your workspace, and they are read-only. The source and target environment endpoints help a client discover valid environments before it creates a grant. Every call is scoped to the caller's own workspace.

Rate limits ​

Cross-workspace sharing developer API resources have the following rate limits:

Quick reference ​

How the API references environments and assets ​

The cross-workspace sharing API uses the following identifiers and conventions:

• Grants

• Each grant is identified by a unique string handle, such as cwsgr-2f8h1k-a3x9qz-1. A single grant can share from multiple source environments at once. The environments array carries one entry for each source environment.

• Environments

• Environments are referenced by their internal id. A grant shares from a source_environment_id in your own workspace to one or more target_environment_ids. Targets must be same-type siblings of the source, so a prod source shares to prod targets, in the same Automation HQ organization and the same data center. Use the List source environments and List target environments endpoints to discover valid IDs before you create a grant.

• Assets

• Assets are referenced by id and type. Cross-workspace sharing supports Event streams topics, so type is Topic. The asset id is the topic's ID, the same identifier the Event streams API uses. This API represents the asset id as a string even though the Event streams topic ID is an integer, because cross-workspace sharing is designed to accommodate future asset types whose IDs aren't numbers. Quote the ID when you use it here.

• Access levels

• The access_levels array grants one or both of read and write for an asset. These map to the Subscribe and Publish access levels shown in the cross-workspace sharing UI. Both outgoing and incoming grants represent access levels as an array.

List outgoing grants ​

Retrieves a list of grants owned by the caller's workspace, with optional name filtering and sorting.

GET /api/cross_workspace/grants

Query parameters ​

Sample request ​

This request retrieves outgoing grants that match the name Orders, sorted by name.

curl  -g -X GET "https://www.workato.com/api/cross_workspace/grants?name=Orders&sort=name&page[number]=1&page[size]=100" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": [
        {
            "handle": "cwsgr-2f8h1k-a3x9qz-1",
            "name": "Orders topic to EU and APAC",
            "description": "Share prod orders stream",
            "created_by": { "name": "Sasha Patel" },
            "created_at": "2026-06-30T12:00:00.000Z",
            "updated_at": "2026-06-30T12:00:00.000Z",
            "environments": [
                {
                    "source_environment_id": 123,
                    "source_environment_type": "prod",
                    "target_environments": [
                        { "id": 456, "type": "prod", "workspace_id": 17293, "workspace_name": "Acme EU" }
                    ],
                    "assets": [
                        { "id": "48213", "name": "orders", "type": "Topic", "access_levels": ["read", "write"] }
                    ]
                }
            ]
        }
    ],
    "total": 42,
    "page": { "number": 1, "size": 100 }
}

Get an outgoing grant ​

Retrieves a single grant owned by the caller's workspace, resolved by handle.

GET /api/cross_workspace/grants/:handle

URL parameters ​

Sample request ​

This request retrieves the grant with the handle cwsgr-2f8h1k-a3x9qz-1.

curl  -X GET "https://www.workato.com/api/cross_workspace/grants/cwsgr-2f8h1k-a3x9qz-1" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": {
        "handle": "cwsgr-2f8h1k-a3x9qz-1",
        "name": "Orders topic to EU and APAC",
        "description": "Share prod orders stream",
        "created_by": { "name": "Sasha Patel" },
        "created_at": "2026-06-30T12:00:00.000Z",
        "updated_at": "2026-06-30T12:00:00.000Z",
        "environments": [
            {
                "source_environment_id": 123,
                "source_environment_type": "prod",
                "target_environments": [
                    { "id": 456, "type": "prod", "workspace_id": 17293, "workspace_name": "Acme EU" }
                ],
                "assets": [
                    { "id": "48213", "name": "orders", "type": "Topic", "access_levels": ["read", "write"] }
                ]
            }
        ]
    }
}

A grant that isn't owned by the caller's workspace returns 404.

Create a grant ​

Creates a grant in the caller's workspace.

POST /api/cross_workspace/grants

Body parameters ​

Sample request ​

This request creates a grant that shares the orders topic from source environment 123 with two target environments.

curl  -X POST "https://www.workato.com/api/cross_workspace/grants" \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "name": "Orders topic to EU and APAC",
            "description": "Share prod orders stream",
            "environments": [
                {
                    "source_environment_id": 123,
                    "target_environment_ids": [456, 789],
                    "assets": [
                        { "id": "48213", "type": "Topic", "access_levels": ["read", "write"] }
                    ]
                }
            ]
         }'

Response ​

{
    "data": {
        "handle": "cwsgr-2f8h1k-a3x9qz-1",
        "name": "Orders topic to EU and APAC",
        "description": "Share prod orders stream",
        "created_by": { "name": "Sasha Patel" },
        "created_at": "2026-06-30T12:00:00.000Z",
        "updated_at": "2026-06-30T12:00:00.000Z",
        "environments": [
            {
                "source_environment_id": 123,
                "source_environment_type": "prod",
                "target_environments": [
                    { "id": 456, "type": "prod", "workspace_id": 17293, "workspace_name": "Acme EU" },
                    { "id": 789, "type": "prod", "workspace_id": 40021, "workspace_name": "Acme APAC" }
                ],
                "assets": [
                    { "id": "48213", "name": "orders", "type": "Topic", "access_levels": ["read", "write"] }
                ]
            }
        ]
    }
}

This endpoint returns 201 on success. It returns 400 if the body fails validation, including a target_environment_id equal to its own source, a target of a different environment type or outside the source's Automation HQ organization, or an asset not owned by its source environment. Each rule reports its own message, so a request that fails more than one rule receives one message for each failing rule.

Update a grant ​

Updates a grant owned by the caller's workspace. The request accepts the same body shape as Create a grant, applied as a partial update for each source environment. Each environments entry is a partial slice keyed by source_environment_id. An omitted target_environment_ids or assets leaves that side unchanged, and an explicit empty array clears it.

PUT /api/cross_workspace/grants/:handle

URL parameters ​

Body parameters ​

The request accepts the same fields as the Create a grant endpoint, applied as a partial update for each source environment.

Sample request ​

This request updates the grant with the handle cwsgr-2f8h1k-a3x9qz-1 to share source environment 123 with a single target environment.

curl  -X PUT "https://www.workato.com/api/cross_workspace/grants/cwsgr-2f8h1k-a3x9qz-1" \
      -H 'Authorization: Bearer <api_token>' \
      -H "Content-Type: application/json" \
      -d '{
            "name": "Orders topic to EU only",
            "environments": [
                { "source_environment_id": 123, "target_environment_ids": [456] }
            ]
         }'

Response ​

{
    "data": {
        "handle": "cwsgr-2f8h1k-a3x9qz-1",
        "name": "Orders topic to EU only",
        "description": "Share prod orders stream",
        "created_by": { "name": "Sasha Patel" },
        "created_at": "2026-06-30T12:00:00.000Z",
        "updated_at": "2026-07-21T09:10:00.000Z",
        "environments": [
            {
                "source_environment_id": 123,
                "source_environment_type": "prod",
                "target_environments": [
                    { "id": 456, "type": "prod", "workspace_id": 17293, "workspace_name": "Acme EU" }
                ],
                "assets": [
                    { "id": "48213", "name": "orders", "type": "Topic", "access_levels": ["read", "write"] }
                ]
            }
        ]
    }
}

This endpoint returns 200 on success. It returns 404 if the handle isn't owned by the caller's workspace, and 400 on validation failure.

Revoke a grant ​

Soft-deletes a grant owned by the caller's workspace.

DELETE /api/cross_workspace/grants/:handle

URL parameters ​

Sample request ​

This request revokes the grant with the handle cwsgr-2f8h1k-a3x9qz-1.

curl  -X DELETE "https://www.workato.com/api/cross_workspace/grants/cwsgr-2f8h1k-a3x9qz-1" \
      -H 'Authorization: Bearer <api_token>'

Response ​

This endpoint returns 204 No Content with an empty body on success. It returns 404 if the handle isn't owned by the caller's workspace, and 400 if the deletion fails.

List incoming grants ​

Retrieves a list of grants that target the caller's workspace. The list view is lightweight. Each source_environments entry carries a has_assets boolean instead of the full asset list. Use the Get an incoming grant endpoint to retrieve the full asset list for a grant.

GET /api/cross_workspace/incoming_grants

Query parameters ​

Sample request ​

This request retrieves the grants that target your workspace.

curl  -g -X GET "https://www.workato.com/api/cross_workspace/incoming_grants?page[number]=1&page[size]=100" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": [
        {
            "handle": "cwsgr-2f8h1k-a3x9qz-1",
            "name": "Orders topic to EU and APAC",
            "description": "Share prod orders stream",
            "created_at": "2026-06-30T12:00:00.000Z",
            "updated_at": "2026-06-30T12:00:00.000Z",
            "source_workspace": { "id": 8842, "name": "Acme Global" },
            "source_environments": [
                { "id": 123, "type": "prod", "has_assets": true }
            ]
        }
    ],
    "total": 3,
    "page": { "number": 1, "size": 100 }
}

Get an incoming grant ​

Retrieves a single grant that targets the caller's workspace. The single-grant view lists the shared assets for each source environment, including their access_levels.

GET /api/cross_workspace/incoming_grants/:handle

URL parameters ​

Sample request ​

This request retrieves the incoming grant with the handle cwsgr-2f8h1k-a3x9qz-1.

curl  -X GET "https://www.workato.com/api/cross_workspace/incoming_grants/cwsgr-2f8h1k-a3x9qz-1" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": {
        "handle": "cwsgr-2f8h1k-a3x9qz-1",
        "name": "Orders topic to EU and APAC",
        "description": "Share prod orders stream",
        "created_at": "2026-06-30T12:00:00.000Z",
        "updated_at": "2026-06-30T12:00:00.000Z",
        "source_workspace": { "id": 8842, "name": "Acme Global" },
        "source_environments": [
            {
                "id": 123,
                "type": "prod",
                "assets": [
                    { "id": "48213", "name": "orders", "type": "Topic", "access_levels": ["read"] }
                ]
            }
        ]
    }
}

A handle that doesn't target the caller's workspace returns 404.

List source environments ​

Retrieves the caller workspace's environments that can act as a grant source.

GET /api/cross_workspace/source_environments

Sample request ​

This request retrieves the environments that can act as a grant source.

curl  -X GET "https://www.workato.com/api/cross_workspace/source_environments" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": [
        { "id": 123, "type": "prod", "name": "Acme Global (prod)" },
        { "id": 124, "type": "test", "name": "Acme Global (test)" }
    ]
}

List target environments ​

Retrieves the sibling environments a given source environment can grant to. Targets are in the same Automation HQ organization and the same data center, and share the same environment type as the source.

GET /api/cross_workspace/target_environments

Query parameters ​

Sample request ​

This request retrieves the environments grantable from source environment 123.

curl  -X GET "https://www.workato.com/api/cross_workspace/target_environments?source_environment_id=123" \
      -H 'Authorization: Bearer <api_token>'

Response ​

{
    "data": [
        { "id": 456, "type": "prod", "workspace_id": 17293, "workspace_name": "Acme EU" },
        { "id": 789, "type": "prod", "workspace_id": 40021, "workspace_name": "Acme APAC" }
    ]
}

This endpoint returns 400 if source_environment_id is omitted, and 404 if it doesn't belong to the caller's workspace.