---
title: create-or-replace-organization-directory-sync-group-configuration
product: vercel
url: /docs/rest-api/organizations/create-or-replace-organization-directory-sync-group-configuration
canonical_url: "https://vercel.com/docs/rest-api/organizations/create-or-replace-organization-directory-sync-group-configuration"
last_updated: 2026-11-18
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about create-or-replace-organization-directory-sync-group-configuration on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# Create or Replace Organization Directory Sync Group Configuration

```http
PUT /v1/organizations/{organizationId}/dsync/groups/{groupId}
```

Create or replace one organization's Directory Sync group configuration. The directory starts syncing when at least one group grants OrgAdmin.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `organizationId` | string | Yes |  |
| `groupId` | string | Yes |  |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `teamId` | string | No | The Team identifier to perform the request on behalf of. |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `If-Match` | string. pattern: `^"\d+"$` | No |  |
| `If-None-Match` | string | No |  |


## Request body

Required: No

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "assignments"
  ],
  "properties": {
    "assignments": {
      "type": "object",
      "properties": {
        "organizationPermissions": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "OrgAdmin"
            ]
          }
        },
        "teamRoles": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "OWNER",
              "MEMBER",
              "DEVELOPER",
              "SECURITY",
              "BILLING",
              "VIEWER",
              "VIEWER_FOR_PLUS",
              "CONTRIBUTOR"
            ]
          }
        },
        "teams": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "required": [
              "teamRoles"
            ]
          }
        }
      }
    }
  }
}
```

## Example request

### TypeScript

```typescript
const response = await fetch('https://api.vercel.com/v1/organizations/organizationId/dsync/groups/groupId?teamId=string&slug=string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "assignments": {
      "organizationPermissions": [],
      "teamRoles": [],
      "teams": "value"
    }
  }),
});

const data = await response.json();
console.log(data);
```

### Next.js

```typescript
'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v1/organizations/organizationId/dsync/groups/groupId?teamId=string&slug=string', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      "assignments": {
        "organizationPermissions": [],
        "teamRoles": [],
        "teams": "value"
      }
    }),
    next: { revalidate: 3600 }
  });

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
}
```

### cURL

```bash
curl -X PUT 'https://api.vercel.com/v1/organizations/organizationId/dsync/groups/groupId?teamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d "{
    \"assignments\": {
      \"organizationPermissions\": [],
      \"teamRoles\": [],
      \"teams\": \"value\"
    }
  }"
```

## Example response

```json
{
  "assignments": {
    "organizationPermissions": [],
    "teamRoles": [],
    "teams": "value"
  },
  "createdAt": "string",
  "directoryGroupId": "example_id",
  "directoryId": "example_id",
  "name": "Example Name",
  "organizationId": "example_id",
  "updatedAt": "string"
}
```

## Responses

### 200: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "A group from the organization's Identity Provider directory, joined with its Directory Sync group configuration when one exists.",
  "required": [
    "assignments",
    "createdAt",
    "directoryGroupId",
    "directoryId",
    "name",
    "organizationId",
    "updatedAt"
  ],
  "properties": {
    "assignments": {
      "type": "object",
      "description": "`null` when the group has no Directory Sync group configuration.",
      "nullable": true,
      "required": [
        "organizationPermissions",
        "teamRoles",
        "teams"
      ],
      "properties": {
        "organizationPermissions": {
          "type": "array",
          "description": "Organization-level permissions assigned to the directory group.",
          "items": {
            "type": "string",
            "enum": [
              "OrgAdmin"
            ]
          }
        },
        "teamRoles": {
          "type": "array",
          "description": "Roles for linked child teams without an explicit team assignment.",
          "items": {
            "type": "string",
            "description": "Roles for linked child teams without an explicit team assignment.",
            "enum": [
              "BILLING",
              "CONTRIBUTOR",
              "DEVELOPER",
              "MEMBER",
              "OWNER",
              "SECURITY",
              "VIEWER",
              "VIEWER_FOR_PLUS"
            ]
          }
        },
        "teams": {
          "type": "object",
          "description": "Replaces the default team roles for each specified child team.",
          "additionalProperties": {
            "type": "object",
            "description": "Replaces the default team roles for each specified child team.",
            "required": [
              "teamRoles"
            ]
          }
        }
      }
    },
    "createdAt": {
      "type": "string",
      "description": "`null` when the group has no Directory Sync group configuration.",
      "nullable": true
    },
    "directoryGroupId": {
      "type": "string"
    },
    "directoryId": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "The group's name in the Identity Provider directory."
    },
    "organizationId": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string",
      "description": "`null` when the group has no Directory Sync group configuration.",
      "nullable": true
    }
  }
}
```

### 400: One of the provided values in the request body is invalid.
One of the provided values in the request query is invalid.
One of the provided values in the headers is invalid

### 401: The request is not authorized.

### 403: You do not have permission to access this resource.

### 404: No description

### 410: No description

### 412: No description

### 428: No description

---

## Related

- [organizations endpoints](/docs/rest-api#organizations)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://vercel.com/openapi.json) (machine-readable, all endpoints)

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
