> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grant Group Workspace Access

> Grant one workspace viewer access to an existing group so it can use the group for assignment. Preserves all existing access, managers and members. Repeating a grant is a no-op; organization-wide groups remain organization-wide. Requires management of the group and destination workspace, in the same organization.

## Authentication and permissions

> **Token requirements:** **User-based token (OAuth)** or **Workspace-scoped API key**.
>
> Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.

| Credential | Access requirements |
| - | - |
| Organization-scoped API key | Unsupported |
| Workspace-scoped API key | **Grant workspace access as a user:** Unsupported **Grant workspace access with a workspace key:** `groups:manage` |
| User-based token (OAuth) | **Grant workspace access as a user:** Supported, subject to permissions **Grant workspace access with a workspace key:** Unsupported |

Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

* **Grant workspace access as a user:** Requires permission to manage the group and the destination workspace’s groups. The group and destination workspace must belong to the same organization. Existing managers, viewers and members are preserved. An already usable group is unchanged, including organization-wide groups.

* **Grant workspace access with a workspace key:** Requires groups:manage and a workspace-scoped key allowing a manager workspace and the destination workspace. Organization-scoped keys cannot perform this operation. The destination must be a live, non-personal workspace in the same organization. Groups that grant a workspace role cannot be changed with a workspace key. Synced groups can be shared without changing their source-owned members. Existing configuration-protection checks apply.


## OpenAPI

````yaml /sections/api-reference/openapi-spec-v2.yaml post /v2/groups/{id}/workspace-access
openapi: 3.1.0
info:
  title: Serval Public API
  description: Serval Public API
  contact:
    name: Serval
    url: https://serval.com
    email: support@serval.com
  license:
    name: Serval License
    url: https://serval.com/license
  version: 2.0.0
servers:
  - url: https://public.api.serval.com
security:
  - BearerAuth: []
tags:
  - name: Access Membership API
  - name: Access Policy API
  - name: Access Policy Approval Procedure API
  - name: Access Profile API
  - name: Access Relationship API
  - name: Access Request API
  - name: Agent API
  - name: Alerts API
  - name: Analytics API
  - name: App Instance API
  - name: App Resource API
  - name: App Resource Role API
  - name: Approval Delegation API
  - name: Approval Procedure API
  - name: Approval Request API
  - name: Assignment Rules API
  - name: Audit Log API
  - name: Billing API
  - name: Browser API
  - name: Campaign API
  - name: Change Blackout API
  - name: Change Model API
  - name: Connected Channels API
  - name: Custom Field API
  - name: Custom Role API
  - name: Custom Service API
  - name: Dashboards API
  - name: Email Intake API
  - name: Entity API
  - name: Entity Field Mapping API
  - name: Entity Ingestion Config API
  - name: Entity Type API
  - name: Folder API
  - name: Forms
  - name: Forms API
  - name: Group API
  - name: Guidance API
  - name: Help Agent API
  - name: Improvement Request API
  - name: Journey API
  - name: Knowledge API
  - name: Knowledge Base API
  - name: One-Time Window API
  - name: Package API
  - name: Platform Migration API
  - name: Project API
  - name: Report API
  - name: Review API
  - name: Role Sync API
  - name: Roles API
  - name: SLA API
  - name: Schedule API
  - name: Skills API
  - name: Tag API
  - name: Ticket API
  - name: Ticket Import API
  - name: Ticket Type API
  - name: Topic API
  - name: User API
  - name: User Relationship API
  - name: Widgets API
  - name: Worker API
  - name: Workflow API
  - name: Workflow Approval Procedure API
  - name: Workflow Run API
  - name: Workspace API
  - name: Workspace Group API
  - name: Workspace SDLC Settings API
  - name: Workspace User API
paths:
  /v2/groups/{id}/workspace-access:
    post:
      tags:
        - Group API
      summary: Grant Group Workspace Access
      description: >-
        Grant one workspace viewer access to an existing group so it can use the
        group for assignment. Preserves all existing access, managers and
        members. Repeating a grant is a no-op; organization-wide groups remain
        organization-wide. Requires management of the group and destination
        workspace, in the same organization.
      operationId: svrelay.publicv2.PublicAPIServiceV2.GrantGroupWorkspaceAccess
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            title: id
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                teamId:
                  type: string
                  title: team_id
              title: GrantGroupWorkspaceAccessRequest
              required:
                - teamId
              additionalProperties: false
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/svauth.public.GrantGroupWorkspaceAccessResponse
      security:
        - BearerAuth: []
components:
  schemas:
    svauth.public.GrantGroupWorkspaceAccessResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/svauth.public.Group'
          title: data
          x-stainless-terraform-configurability: optional
      title: GrantGroupWorkspaceAccessResponse
      additionalProperties: false
    svauth.public.Group:
      type: object
      properties:
        id:
          type: string
          title: id
          readOnly: true
          x-stainless-terraform-configurability: computed
        name:
          type: string
          title: name
          x-stainless-terraform-configurability: optional
        organizationId:
          type: string
          title: organization_id
          readOnly: true
          x-stainless-terraform-configurability: computed
        createdAt:
          $ref: '#/components/schemas/google.protobuf.Timestamp'
          title: created_at
          readOnly: true
          x-stainless-terraform-configurability: computed
        deletedAt:
          oneOf:
            - $ref: '#/components/schemas/google.protobuf.Timestamp'
            - type: 'null'
          title: deleted_at
          readOnly: true
          x-stainless-terraform-configurability: computed
        userIds:
          type: array
          items:
            type: string
          title: user_ids
          x-stainless-terraform-configurability: optional
        managerTeamIds:
          type: array
          items:
            type: string
            readOnly: true
          title: manager_team_ids
          description: >-
            Workspaces whose group-managers manage this group. Empty = org-wide
            visibility
             (the group may still carry individual owners; see access).
          readOnly: true
          x-stainless-terraform-configurability: computed
        scopedId:
          type: string
          title: scoped_id
          readOnly: true
          x-stainless-terraform-configurability: computed
        externallyManaged:
          type: boolean
          title: externally_managed
          readOnly: true
          x-stainless-terraform-configurability: computed
        configurationTeamId:
          type:
            - string
            - 'null'
          title: configuration_team_id
          readOnly: true
          x-stainless-terraform-configurability: computed
        access:
          $ref: '#/components/schemas/svauth.public.GroupAccess'
          title: access
          readOnly: true
          x-stainless-terraform-configurability: computed
      title: Group
      additionalProperties: false
    google.protobuf.Timestamp:
      type: string
      examples:
        - '2025-01-15T01:30:15.000Z'
        - '2025-06-01T00:00:00.000Z'
      format: date-time
      description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
    svauth.public.GroupAccess:
      type: object
      properties:
        managerUserIds:
          type: array
          items:
            type: string
          title: manager_user_ids
          x-stainless-terraform-configurability: optional
        managerTeamIds:
          type: array
          items:
            type: string
          title: manager_team_ids
          x-stainless-terraform-configurability: optional
        viewerUserIds:
          type: array
          items:
            type: string
          title: viewer_user_ids
          x-stainless-terraform-configurability: optional
        viewerTeamIds:
          type: array
          items:
            type: string
          title: viewer_team_ids
          x-stainless-terraform-configurability: optional
      title: GroupAccess
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.