Add a Collaborator

You can set some of the fields available in the collaborator object, below we only list the properties in the example and the possible required fields.

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

Path Parameters

:space_id
required number

Numeric ID of a space

Request Body Properties

email
string

Email that will be used in the space interface for collaborator or collaborator SSO ID required
role
string

The role name of the collaborator. It could be admin, editor, or set to a roleid. For custom roles - while adding one role, you need to set it to the role_id , and for adding multiple roles, you need to set the value to multi required
space_role_id
number

Numeric id connected with a role, usually an array of ids with more than one role required
space_role_ids
number[]

An array of numeric ids for multiple roles in a space for a collaborator. Make sure to set allow_multiple_roles_creation to true while using this.

permissions

enum[]

Permissions for a collaborator, usually is set to can_subscribe for a collaborator.

Permission	Description
read_stories	View stories without editing
save_stories	Edit and save stories
publish_stories	Publish stories to the live environment
unpublish_stories	Unpublish stories from the live environment
publish_folders	Publish entire folders and their contents
unpublish_folders	Unpublish folders and their contents
deploy_stories	Deploy pipeline stories
delete_stories	Permanently delete stories
edit_image	Edit images in the asset manager
view_composer	View the Visual Editor
change_alternate_group	Change alternate content groupings (for i18n or variants)
move_story	Move stories between folders
edit_story_slug	Edit the URL slug of a story
view_content	Controls visibility of content entries. Without this, all content is hidden unless explicitly granted. To give read-only access to others, enable allow reading content permission.
view_folders	Controls visibility of folders. Without this, all folders are hidden unless explicitly granted. To give read-only access to others, enable allow reading content permission.
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 keys inside datasources
access_commerce	Access commerce-related features
manage_block_library	Manage components in the Block Library
hide_asset_folders	Hides assets and folders (including subfolders) that the role doesn't have upload permission for. In the UI, you can specify which folders are accessible.

allow_multiple_roles_creation
boolean

Boolean value, if true you can add multiple role ids for a collaborator

Response Properties

collaborator

The Collaborator Object

The collaborator object

user
object

The user object inside a collaborator object
- id
  number
  
  The user ID
- firstname
  string
  
  First name of collaborator
- lastname
  string
  
  Last name of collaborator
- alt_email
  string
  
  Email of collaborator
- avatar
  string
  
  Avatar of collaborator usually an image
- userid
  string
  
  User ID of collaborator
- friendly_name
  string
  
  Friendly name of collaborator
role
string

Role of the collaborator, could be admin, editor or custom roles
user_id
number

Numeric ID of the user

permissions

enum[]

Allow specific actions for collaborator in interface and add the permission as array of strings

Permission	Description
read_stories	View stories without editing
save_stories	Edit and save stories
publish_stories	Publish stories to the live environment
unpublish_stories	Unpublish stories from the live environment
publish_folders	Publish entire folders and their contents
unpublish_folders	Unpublish folders and their contents
deploy_stories	Deploy pipeline stories
delete_stories	Permanently delete stories
edit_image	Edit images in the asset manager
view_composer	View the Visual Editor
change_alternate_group	Change alternate content groupings (for i18n or variants)
move_story	Move stories between folders
edit_story_slug	Edit the URL slug of a story
view_content	Controls visibility of content entries. Without this, all content is hidden unless explicitly granted. To give read-only access to others, enable allow reading content permission.
view_folders	Controls visibility of folders. Without this, all folders are hidden unless explicitly granted. To give read-only access to others, enable allow reading content permission.
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 keys inside datasources
access_commerce	Access commerce-related features
manage_block_library	Manage components in the Block Library
hide_asset_folders	Hides assets and folders (including subfolders) that the role doesn't have upload permission for. In the UI, you can specify which folders are accessible.

allowed_paths
number[]

Story ids the user should have access to (acts as whitelist). If no item is selected the user has rights to access all content items.
field_permissions
string[]

Hide specific fields for this user with an array of strings with the schema
id
number

Numeric id of collaborator
space_role_id
number

Numeric ID of the space role
space_role_ids
number[]

Array of space role ids
space_id
number

Numeric id of the collaborator space

Select a Language

Request

curl "https://mapi.storyblok.com/v1/spaces/656/collaborators/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -d "{\"email\": \"api.test@storyblok.com\",\"role\": \"admin\",\"space_role_id\": \"\",\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.post('cdn/spaces/656/collaborators/', {
    
    "email": "api.test@storyblok.com",
    "role": "admin",
    "space_role_id": "",
    "permissions": [],
    "space_role_ids" : [],
    "allow_multiple_roles_creation": false
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$payload = [
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "admin",
    "space_role_id" =>  "",
    "permissions" =>  [],
    "space_role_ids"  =>  [],
    "allow_multiple_roles_creation" =>  false
];

$client->post('/spaces/656/collaborators/', $payload)->getBody();

Request

require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "admin",
    "space_role_id" =>  "",
    "permissions" =>  [],
    "space_role_ids"  =>  [],
    "allow_multiple_roles_creation" =>  false
}

client.post('/spaces/656/collaborators/', payload)

Request

HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/collaborators/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"email\": \"api.test@storyblok.com\",\"role\": \"admin\",\"space_role_id\": \"\",\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}")
  .asString();

Request

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/collaborators/");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"email\": \"api.test@storyblok.com\",\"role\": \"admin\",\"space_role_id\": \"\",\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

import Foundation

let headers = [
  "Content-Type": "application/json",
  "Authorization": "YOUR_OAUTH_TOKEN"
]

let postData = NSData(data: "{\"email\": \"api.test@storyblok.com\",\"role\": \"admin\",\"space_role_id\": \"\",\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}".data(using: String.Encoding.utf8)!)
let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/collaborators/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)

request.method = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Request

import requests

url = "https://mapi.storyblok.com/v1/spaces/656/collaborators/"

querystring = {}

payload = "{\"email\": \"api.test@storyblok.com\",\"role\": \"admin\",\"space_role_id\": \"\",\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}"
headers = {
  'Content-Type': "application/json",
  'Authorization': "YOUR_OAUTH_TOKEN"
}

response = requests.request("POST", url, data=payload, headers=headers, params=querystring)

print(response.text)

Request for adding a collaborator with one custom role.

Request

curl "https://mapi.storyblok.com/v1/spaces/656/collaborators/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -d "{\"email\": \"api.test@storyblok.com\",\"role\": \"62454\",\"space_role_id\": 62454,\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.post('cdn/spaces/656/collaborators/', {
    
    "email": "api.test@storyblok.com",
    "role": "62454",
    "space_role_id": 62454,
    "permissions": [],
    "space_role_ids" : [],
    "allow_multiple_roles_creation": false
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$payload = [
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "62454",
    "space_role_id" =>  62454,
    "permissions" =>  [],
    "space_role_ids"  =>  [],
    "allow_multiple_roles_creation" =>  false
];

$client->post('/spaces/656/collaborators/', $payload)->getBody();

Request

require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "62454",
    "space_role_id" =>  62454,
    "permissions" =>  [],
    "space_role_ids"  =>  [],
    "allow_multiple_roles_creation" =>  false
}

client.post('/spaces/656/collaborators/', payload)

Request

HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/collaborators/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"email\": \"api.test@storyblok.com\",\"role\": \"62454\",\"space_role_id\": 62454,\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}")
  .asString();

Request

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/collaborators/");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"email\": \"api.test@storyblok.com\",\"role\": \"62454\",\"space_role_id\": 62454,\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

import Foundation

let headers = [
  "Content-Type": "application/json",
  "Authorization": "YOUR_OAUTH_TOKEN"
]

let postData = NSData(data: "{\"email\": \"api.test@storyblok.com\",\"role\": \"62454\",\"space_role_id\": 62454,\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}".data(using: String.Encoding.utf8)!)
let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/collaborators/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)

request.method = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Request

import requests

url = "https://mapi.storyblok.com/v1/spaces/656/collaborators/"

querystring = {}

payload = "{\"email\": \"api.test@storyblok.com\",\"role\": \"62454\",\"space_role_id\": 62454,\"permissions\": [],\"space_role_ids\" : [],\"allow_multiple_roles_creation\": false}"
headers = {
  'Content-Type': "application/json",
  'Authorization': "YOUR_OAUTH_TOKEN"
}

response = requests.request("POST", url, data=payload, headers=headers, params=querystring)

print(response.text)

Request for adding a collaborator with multiple custom roles.

Request

curl "https://mapi.storyblok.com/v1/spaces/656/collaborators/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_OAUTH_TOKEN" \
  -d "{\"email\": \"api.test@storyblok.com\",\"role\": \"multi\",\"permissions\": [],\"space_role_ids\" : [62454, 123123],\"allow_multiple_roles_creation\": true}"

Request

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.post('cdn/spaces/656/collaborators/', {
    
    "email": "api.test@storyblok.com",
    "role": "multi",
    "permissions": [],
    "space_role_ids" : [62454, 123123],
    "allow_multiple_roles_creation": true
})
  .then(response => {
    console.log(response)
  }).catch(error => { 
    console.log(error)
  })

Request

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$payload = [
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "multi",
    "permissions" =>  [],
    "space_role_ids"  =>  [62454, 123123],
    "allow_multiple_roles_creation" =>  true
];

$client->post('/spaces/656/collaborators/', $payload)->getBody();

Request

require 'storyblok'
client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')

payload = {
    
    "email" =>  "api.test@storyblok.com",
    "role" =>  "multi",
    "permissions" =>  [],
    "space_role_ids"  =>  [62454, 123123],
    "allow_multiple_roles_creation" =>  true
}

client.post('/spaces/656/collaborators/', payload)

Request

HttpResponse<String> response = Unirest.post("https://mapi.storyblok.com/v1/spaces/656/collaborators/")
  .header("Content-Type", "application/json")
  .header("Authorization", "YOUR_OAUTH_TOKEN")
  .body("{\"email\": \"api.test@storyblok.com\",\"role\": \"multi\",\"permissions\": [],\"space_role_ids\" : [62454, 123123],\"allow_multiple_roles_creation\": true}")
  .asString();

Request

var client = new RestClient("https://mapi.storyblok.com/v1/spaces/656/collaborators/");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "YOUR_OAUTH_TOKEN");
request.AddParameter("application/json", "{\"email\": \"api.test@storyblok.com\",\"role\": \"multi\",\"permissions\": [],\"space_role_ids\" : [62454, 123123],\"allow_multiple_roles_creation\": true}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Request

import Foundation

let headers = [
  "Content-Type": "application/json",
  "Authorization": "YOUR_OAUTH_TOKEN"
]

let postData = NSData(data: "{\"email\": \"api.test@storyblok.com\",\"role\": \"multi\",\"permissions\": [],\"space_role_ids\" : [62454, 123123],\"allow_multiple_roles_creation\": true}".data(using: String.Encoding.utf8)!)
let request = NSMutableURLRequest(url: NSURL(string: "https://mapi.storyblok.com/v1/spaces/656/collaborators/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)

request.method = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Request

import requests

url = "https://mapi.storyblok.com/v1/spaces/656/collaborators/"

querystring = {}

payload = "{\"email\": \"api.test@storyblok.com\",\"role\": \"multi\",\"permissions\": [],\"space_role_ids\" : [62454, 123123],\"allow_multiple_roles_creation\": true}"
headers = {
  'Content-Type': "application/json",
  'Authorization': "YOUR_OAUTH_TOKEN"
}

response = requests.request("POST", url, data=payload, headers=headers, params=querystring)

print(response.text)