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
publish_stories	Allow publishing of content entries
save_stories	Allow editing and saving of content entries
edit_datasources	Allow editing and saving of datasources
access_commerce	Allow access to commerce app
edit_story_slug	Deny the change of slugs of content entries
move_story	Deny moving of content entries
view_composer	Deny access to visual composer

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
publish_stories	Allow publishing of content entries
save_stories	Allow editing and saving of content entries
edit_datasources	Allow editing and saving of datasources
access_commerce	Allow access to commerce app
edit_story_slug	Deny the change of slugs of content entries
move_story	Deny moving of content entries
view_composer	Deny access to visual composer

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('/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\ManagementClient('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)->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('/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\ManagementClient('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)->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('/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\ManagementClient('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)->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)

Prev Retrieve Multiple Collaborators

Next Delete a Collaborator