---
title: "Share app with groups"
method: POST
path: "/api/apps/{app_id}/group-shares"
---

# Share app with groups

`POST /api/apps/{app_id}/group-shares`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/apps/{app_id}/group-shares`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Shares the app with one or more workspace groups, giving every member of each group access to the app.

All the groups get the same `role`. A member's role in the app is the highest of the role you gave them directly and the roles of all the groups they're in that the app is shared with. Members usually get access right away, and always by their next sign-in. Members your identity provider synced who don't have a Base44 account yet get access once they have one. Each member who gets access is also sent an invitation email, at most once per app.

Each group succeeds or fails on its own, so read `results` rather than treating a successful response as every group shared. Sending a group the app is already shared with fails that group with `already_shared` and changes nothing, so retrying is safe. Change a share's role afterwards with [Update group share](/api-reference/update-group-share).

You need editor access to the app, and an editor or admin role in the app's workspace. Your workspace's plan must include workspace groups.

This is limited to 30 requests per minute. A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>This endpoint accepts a personal API key belonging to a user with editor access to the app. A read-only key is refused, and workspace API keys are not accepted.</Note>

## Path parameters

- `app_id` string, required: ID of the app.

## Request body

- CreateSharesRequest
  - `group_ids` string[], required: IDs of the workspace groups to share the app with, 1 to 50. A repeated ID counts once.
  - `role` string, nullable: App role every member of these groups gets, one of the roles defined on the app's User entity. Leave it out, or send `null`, to assign no role, so members get the default `user` role.

## Response `200`

One result per group.

- CreateSharesResponse
  - `results` CreateShareResult[], required: One result per group, in the order you sent them.
    - `group_id` string, required: ID of the group, as you sent it.
    - `success` boolean, required: Whether the app is now shared with the group by this call.
    - `error` string, nullable, required: Why the group wasn't shared, or `null` on success. `group_not_found` means the ID isn't a group in the app's workspace, and `already_shared` means the app is already shared with it.

## Other responses

- `401`: Missing or invalid credentials.
- `402`: Your workspace's plan doesn't include workspace groups.
- `403`: You don't have editor access to this app, you aren't an editor or admin in the app's workspace, or your API key is read-only.
- `404`: App not found.
- `422`: `group_ids` is missing, empty, or has more than 50 IDs, or `role` isn't one of the roles defined on the app's User entity.
- `429`: Rate limit exceeded. The base limit is 30 requests per minute. Wait the number of seconds in the `Retry-After` header before you retry.

## Changes

> 58 revisions in range; 1 not diffed.

- **2026-10-12** `5e139db2e643`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-09** `fc604cdcc3a2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/apps/:app_id/group-shares/post.md)

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/fa29e915c226?raw)