---
title: Add a Collaborator
description: Add collaborators with specific roles and permissions available in the collaborator object
url: https://storyblok.com/docs/api/management/collaborators/add-a-collaborator
---

# Add a Collaborator

POST

```html
https://mapi.storyblok.com/v1/spaces/:space_id/collaborators/
```

Add collaborators with specific roles and permissions.

The following list includes only required fields—find all available properties in the [collaborator object](/docs/api/management/collaborators/the-collaborator-object/) page.

## Path parameters

-   `:space_id` (required) (number)
    
    Numeric ID of a space.
    

## Request body properties

-   `email` (required) (string)
    
    The collaborator’s email or SSO ID.
    
-   `role` (required) (string)
    
    The role name of the collaborator. It could be a default role (admin or editor), or a custom role listed with a `role_id`.
    
-   `space_role_id` (required) (number)
    
    Numeric ID associated with a single custom role.
    
-   `space_role_ids` (number\[\])
    
    An array of numeric IDs associated with each custom role assigned to a single collaborator. Set `allow_multiple_roles_creation` to `true` to enable multi-role.
    
-   `permissions` (enum\[\])
    
    An array of strings that define the role’s permissions.
    
    > [!TIP]
    > Find the full list of permissions in the [space role object](/docs/api/management/space-roles/the-space-role-object/) reference page.
    
    | Permission | Description |
    | --- | --- |
    | `read_stories` | Read-only access to stories |
    | `save_stories` | Edit and save stories |
    | `publish_stories` | Publish stories |
    | `unpublish_stories` | Unpublish stories |
    | `publish_folders` | Publish folders (including stories contained within) |
    | `unpublish_folders` | Unpublish folders (including stories contained within) |
    | `deploy_stories` | Deploy pipeline stories |
    | `delete_stories` | Permanently delete stories |
    | `edit_image` | Edit images in the Image Editor |
    | `view_composer` | Use the Visual Editor |
    | `change_alternate_group` | Change alternate content groupings (for internationalization or variants) |
    | `move_story` | Move stories between folders |
    | `edit_story_slug` | Edit a story URL |
    | `view_content` | If checked, hides all stories except those defined in `allowed_paths` (**Permissions** → **Content** → **Folder/Content item permissions**) |
    | `view_folders` | If checked, hides all folders except those defined in `allowed_paths` (**Permissions** → **Content** → **Folder/Content item permissions**) |
    | `view_draft_json` | View the draft `JSON` payload of stories |
    | `view_published_json` | View the published `JSON` payload of stories |
    | `manage_tags` | Create, edit, or delete tags |
    | `edit_datasources` | Edit datasources |
    | `edit_datasource_keys` | Edit datasources keys |
    | `access_commerce` | Access e-commerce features (if available) |
    | `manage_block_library` | Create, move, and edit blocks and folders |
    | `hide_asset_folders` | If checked, hides all assets and folders except those defined in `asset_folder_ids` (**Permissions** → **Assets** → **Asset Folder Permissions**) |
    
-   `allow_multiple_roles_creation` (boolean)
    
    Set to `true` to add multiple role IDs for a single collaborator.
    

## Response properties

-   `collaborator` (The Collaborator Object )
    
    The [collaborator object](/docs/api/management/collaborators/the-collaborator-object)
    

## Examples

-   cURL
    
    ```shellscript
    curl "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/" \
      -X POST \
      -H "Authorization: YOUR_OAUTH_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"allow_multiple_roles_creation\":false,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"admin\",\"space_role_id\":null,\"space_role_ids\":[]}"
    ```
    
-   JS
    
    ```javascript
    // storyblok-js-client@>=7, node@>=18
    import Storyblok from "storyblok-js-client";
    
    const storyblok = new Storyblok({
      oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN",
    });
    
    try {
      const response = await storyblok.post('spaces/288868932106293/collaborators/', {
        "allow_multiple_roles_creation": false,
        "email": "api.test@storyblok.com",
        "permissions": [],
        "role": "admin",
        "space_role_id": null,
        "space_role_ids": []
      })
      console.log({ response })
    } catch (error) {
      console.log(error)
    }
    ```
    
-   PHP
    
    ```php
    $client = new \Storyblok\ManagementClient('YOUR_OAUTH_TOKEN');
    
    $payload = ["allow_multiple_roles_creation" => false,"email" => "api.test@storyblok.com","permissions" => [],"role" => "admin","space_role_id" => null,"space_role_ids" => []];
    
    $client->post('spaces/288868932106293/collaborators/', $payload)->getBody();
    ```
    
-   Java
    
    ```java
    HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/")
      .header("Content-Type", "application/json")
      .header("Authorization", "YOUR_OAUTH_TOKEN")
      .body({"allow_multiple_roles_creation":false,"email":"api.test@storyblok.com","permissions":[],"role":"admin","space_role_id":null,"space_role_ids":[]})
      .asString();
    ```
    
-   C#
    
    ```csharp
    var client = new RestClient("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/");
    var request = new RestRequest(Method.POST);
    
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
    request.AddParameter("application/json", "{\"allow_multiple_roles_creation\":false,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"admin\",\"space_role_id\":null,\"space_role_ids\":[]}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
    ```
    
-   Python
    
    ```python
    import requests
    
    url = "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/"
    
    querystring = {}
    
    payload = {"allow_multiple_roles_creation":false,"email":"api.test@storyblok.com","permissions":[],"role":"admin","space_role_id":null,"space_role_ids":[]}
    headers = {
      'Content-Type': "application/json",
      'Authorization': "YOUR_OAUTH_TOKEN"
    }
    
    response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
    
    print(response.text)
    ```
    
-   Ruby
    
    ```ruby
    require 'storyblok'
    client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')
    
    payload = {"allow_multiple_roles_creation" => false,"email" => "api.test@storyblok.com","permissions" => [],"role" => "admin","space_role_id" => null,"space_role_ids" => []}
    
    client.post('spaces/288868932106293/collaborators/', payload)
    ```
    
-   Swift
    
    ```swift
    let storyblok = URLSession(storyblok: .mapi(accessToken: .oauth("YOUR_OAUTH_TOKEN")))
    var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/collaborators/")
    request.httpMethod = "POST"
    request.httpBody = try JSONSerialization.data(withJSONObject: [
        "allow_multiple_roles_creation": false,
        "email": "api.test@storyblok.com",
        "permissions": [ ],
        "role": "admin",
        "space_role_id": nil,
        "space_role_ids": [ ],
    ])
    let (data, _) = try await storyblok.data(for: request)
    print(try JSONSerialization.jsonObject(with: data))
    ```
    
-   Kotlin
    
    ```kotlin
    val client = HttpClient {
        install(Storyblok(MAPI)) {
            accessToken = OAuth("YOUR_OAUTH_TOKEN")
        }
    }
    
    val response = client.post("spaces/288868932106293/collaborators/") {
        setBody(buildJsonObject {
            put("allow_multiple_roles_creation", false)
            put("email", "api.test@storyblok.com")
            putJsonArray("permissions") { }
            put("role", "admin")
            put("space_role_id", null)
            putJsonArray("space_role_ids") { }
        })
    }
    
    println(response.body<JsonElement>())
    ```

Request for adding a collaborator with one custom role.

-   cURL
    
    ```shellscript
    curl "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/" \
      -X POST \
      -H "Authorization: YOUR_OAUTH_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"allow_multiple_roles_creation\":false,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"62454\",\"space_role_id\":62454,\"space_role_ids\":[]}"
    ```
    
-   JS
    
    ```javascript
    // storyblok-js-client@>=7, node@>=18
    import Storyblok from "storyblok-js-client";
    
    const storyblok = new Storyblok({
      oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN",
    });
    
    try {
      const response = await storyblok.post('spaces/288868932106293/collaborators/', {
        "allow_multiple_roles_creation": false,
        "email": "api.test@storyblok.com",
        "permissions": [],
        "role": "62454",
        "space_role_id": 62454,
        "space_role_ids": []
      })
      console.log({ response })
    } catch (error) {
      console.log(error)
    }
    ```
    
-   PHP
    
    ```php
    $client = new \Storyblok\ManagementClient('YOUR_OAUTH_TOKEN');
    
    $payload = ["allow_multiple_roles_creation" => false,"email" => "api.test@storyblok.com","permissions" => [],"role" => "62454","space_role_id" => 62454,"space_role_ids" => []];
    
    $client->post('spaces/288868932106293/collaborators/', $payload)->getBody();
    ```
    
-   Java
    
    ```java
    HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/")
      .header("Content-Type", "application/json")
      .header("Authorization", "YOUR_OAUTH_TOKEN")
      .body({"allow_multiple_roles_creation":false,"email":"api.test@storyblok.com","permissions":[],"role":"62454","space_role_id":62454,"space_role_ids":[]})
      .asString();
    ```
    
-   C#
    
    ```csharp
    var client = new RestClient("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/");
    var request = new RestRequest(Method.POST);
    
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
    request.AddParameter("application/json", "{\"allow_multiple_roles_creation\":false,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"62454\",\"space_role_id\":62454,\"space_role_ids\":[]}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
    ```
    
-   Python
    
    ```python
    import requests
    
    url = "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/"
    
    querystring = {}
    
    payload = {"allow_multiple_roles_creation":false,"email":"api.test@storyblok.com","permissions":[],"role":"62454","space_role_id":62454,"space_role_ids":[]}
    headers = {
      'Content-Type': "application/json",
      'Authorization': "YOUR_OAUTH_TOKEN"
    }
    
    response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
    
    print(response.text)
    ```
    
-   Ruby
    
    ```ruby
    require 'storyblok'
    client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')
    
    payload = {"allow_multiple_roles_creation" => false,"email" => "api.test@storyblok.com","permissions" => [],"role" => "62454","space_role_id" => 62454,"space_role_ids" => []}
    
    client.post('spaces/288868932106293/collaborators/', payload)
    ```
    
-   Swift
    
    ```swift
    let storyblok = URLSession(storyblok: .mapi(accessToken: .oauth("YOUR_OAUTH_TOKEN")))
    var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/collaborators/")
    request.httpMethod = "POST"
    request.httpBody = try JSONSerialization.data(withJSONObject: [
        "allow_multiple_roles_creation": false,
        "email": "api.test@storyblok.com",
        "permissions": [ ],
        "role": "62454",
        "space_role_id": 62454,
        "space_role_ids": [ ],
    ])
    let (data, _) = try await storyblok.data(for: request)
    print(try JSONSerialization.jsonObject(with: data))
    ```
    
-   Kotlin
    
    ```kotlin
    val client = HttpClient {
        install(Storyblok(MAPI)) {
            accessToken = OAuth("YOUR_OAUTH_TOKEN")
        }
    }
    
    val response = client.post("spaces/288868932106293/collaborators/") {
        setBody(buildJsonObject {
            put("allow_multiple_roles_creation", false)
            put("email", "api.test@storyblok.com")
            putJsonArray("permissions") { }
            put("role", "62454")
            put("space_role_id", 62454)
            putJsonArray("space_role_ids") { }
        })
    }
    
    println(response.body<JsonElement>())
    ```

Request for adding a collaborator with multiple custom roles.

-   cURL
    
    ```shellscript
    curl "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/" \
      -X POST \
      -H "Authorization: YOUR_OAUTH_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"allow_multiple_roles_creation\":true,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"multi\",\"space_role_id\":null,\"space_role_ids\":[62454,123123]}"
    ```
    
-   JS
    
    ```javascript
    // storyblok-js-client@>=7, node@>=18
    import Storyblok from "storyblok-js-client";
    
    const storyblok = new Storyblok({
      oauthToken: "YOUR_PERSONAL_ACCESS_TOKEN",
    });
    
    try {
      const response = await storyblok.post('spaces/288868932106293/collaborators/', {
        "allow_multiple_roles_creation": true,
        "email": "api.test@storyblok.com",
        "permissions": [],
        "role": "multi",
        "space_role_id": null,
        "space_role_ids": [
          62454,
          123123
        ]
      })
      console.log({ response })
    } catch (error) {
      console.log(error)
    }
    ```
    
-   PHP
    
    ```php
    $client = new \Storyblok\ManagementClient('YOUR_OAUTH_TOKEN');
    
    $payload = ["allow_multiple_roles_creation" => true,"email" => "api.test@storyblok.com","permissions" => [],"role" => "multi","space_role_id" => null,"space_role_ids" => [62454,123123]];
    
    $client->post('spaces/288868932106293/collaborators/', $payload)->getBody();
    ```
    
-   Java
    
    ```java
    HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/")
      .header("Content-Type", "application/json")
      .header("Authorization", "YOUR_OAUTH_TOKEN")
      .body({"allow_multiple_roles_creation":true,"email":"api.test@storyblok.com","permissions":[],"role":"multi","space_role_id":null,"space_role_ids":[62454,123123]})
      .asString();
    ```
    
-   C#
    
    ```csharp
    var client = new RestClient("https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/");
    var request = new RestRequest(Method.POST);
    
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
    request.AddParameter("application/json", "{\"allow_multiple_roles_creation\":true,\"email\":\"api.test@storyblok.com\",\"permissions\":[],\"role\":\"multi\",\"space_role_id\":null,\"space_role_ids\":[62454,123123]}", ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
    ```
    
-   Python
    
    ```python
    import requests
    
    url = "https://mapi.storyblok.com/v1/spaces/288868932106293/collaborators/"
    
    querystring = {}
    
    payload = {"allow_multiple_roles_creation":true,"email":"api.test@storyblok.com","permissions":[],"role":"multi","space_role_id":null,"space_role_ids":[62454,123123]}
    headers = {
      'Content-Type': "application/json",
      'Authorization': "YOUR_OAUTH_TOKEN"
    }
    
    response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
    
    print(response.text)
    ```
    
-   Ruby
    
    ```ruby
    require 'storyblok'
    client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')
    
    payload = {"allow_multiple_roles_creation" => true,"email" => "api.test@storyblok.com","permissions" => [],"role" => "multi","space_role_id" => null,"space_role_ids" => [62454,123123]}
    
    client.post('spaces/288868932106293/collaborators/', payload)
    ```
    
-   Swift
    
    ```swift
    let storyblok = URLSession(storyblok: .mapi(accessToken: .oauth("YOUR_OAUTH_TOKEN")))
    var request = URLRequest(storyblok: storyblok, path: "spaces/288868932106293/collaborators/")
    request.httpMethod = "POST"
    request.httpBody = try JSONSerialization.data(withJSONObject: [
        "allow_multiple_roles_creation": true,
        "email": "api.test@storyblok.com",
        "permissions": [ ],
        "role": "multi",
        "space_role_id": nil,
        "space_role_ids": [
            62454,
            123123,
        ],
    ])
    let (data, _) = try await storyblok.data(for: request)
    print(try JSONSerialization.jsonObject(with: data))
    ```
    
-   Kotlin
    
    ```kotlin
    val client = HttpClient {
        install(Storyblok(MAPI)) {
            accessToken = OAuth("YOUR_OAUTH_TOKEN")
        }
    }
    
    val response = client.post("spaces/288868932106293/collaborators/") {
        setBody(buildJsonObject {
            put("allow_multiple_roles_creation", true)
            put("email", "api.test@storyblok.com")
            putJsonArray("permissions") { }
            put("role", "multi")
            put("space_role_id", null)
            putJsonArray("space_role_ids") {
                add(62454)
                add(123123)
            }
        })
    }
    
    println(response.body<JsonElement>())
    ```

## Pagination

-   [Previous: Collaborators](/docs/api/management/collaborators)
-   [Next: Add a User with SSO](/docs/api/management/collaborators/add-a-user-with-sso)