User Role Assigning

The role type field in the API assigns roles, defining users' platform access to Classic Studio, Creator Studio, and member experience. All new users are created with the default role of member unless stated otherwise.

The role types supported are:

Role: A Firstup application preset that represents the Creator Studio Advanced Permissions Roles, defining the user's overarching responsibilities. Examples are Creator Studio roles include Community Role, Member, Content Creator, Content Publisher, etc.
Scope: What level of application access and permissions are included or restricted in conjunction with their role. For example, a user role could be publisher, but their scope would only include audiences and topics relating to their department or location.
Legacy Roles: Deprecated Classic Studio roles from the past that may still be associated with the user. In most scenarios, these roles are no longer utilized and are not required for current functionality.

Notes:

If no role is specified, new users are assigned the member role by default.
If you want to assign a role other than the default member, you must explicitly set the roles field when provisioning the user.
The API currently supports assigning only one role per user. If multiple roles are provided in a request, the API will return a 422 Unprocessable Entity error.

Role

Sending a predefined role is the simplest way to manage a user's role (access and permissions).

Example of setting a user's role in Creator Studio

Example of Roles schema

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources": [
    {
      "value": "group_admin",
      "display": "Community Admin",
      "type": "primary",
      "enabled": true,
      "contains": [
        "moderate_comments",
        "create_audience",
        "publish_campaign",
        "insights"
      ]
    }
  ]
}

To find out what roles are available, you can send a get request to view the list. You can change a user's role at any time, and add or change their scope.

Setting a user role can be done by one of two ways:

Role String

Set a pre-defined role by Firstup to your user. Set this value from the available enum list: administrator, program_manager, analyst, publisher, channel_contributor, member (default). We recommended this way. Find our predefined role list here.

Example

"roles": [
  "publisher"
]

Role Object

Set legacy roles, custom and advanced roles to your user with custom role scopes (permissions). Set this object type to one of: role, scope, legacy_role.

Example

"roles": [
  { "type": "role", "value": "publisher" }
]

See our Scope section for more guidance and examples.

Before you start

Generate a bearer token.

Get Available Roles

Find out the list of available roles in your community before assigning one to a user.

Optional filtering by origin:

?filter=origin eq "system"
?filter=origin eq "custom"

Response includes:

value (role identifier)
display (human-friendly name)
enabled (status)

Endpoint

GET /scim/v2/roles

Whilst multiple different roles may be available, including any custom-made roles, here are a couple of recommended predefined roles by Firstup that correspond to the same role in Creator Studio:

Role Name	Description
`content_creator`	Lets users create and edit campaigns. The API role contains: `"home"`, `"campaigns"`, `"content_creator_insights"`, `"feed"`, `"use_templates"`, `"set_featured"`, `"send_email"`, `"send_push"`, `"send_to_assistant"`.
`content_editor`	This role gives users the same access as content creator, but with additional permissions to publish, archive and delete campaigns. The API role type contains: `"Home"`, `"Campaigns"`, `"Send_email"`, `"Send_push"`, `"Publish_campaign"`, `"Send_to_assistant"`, `"Set_featured"`, `"Import_users"`, `"Insights"`, `"feed"`
`people_manager`	This role gives users access to all users, topics, audiences templates, email aliases and author aliases. Essentially this role includes all possible scope items, therefore you only need to send this role type. In addition, this role allows the user to add, edit and delete users in their community. The API role type contains: `"Add_import_users"`, `"Configure"`, `"configure_admin"`, `"Configure_admin_activity_feed"`, `"Configure_content"`, `"Create_audience"`, `"home"`, `"No_restrictions"`, `"people"`
`group_admin`	With a few minor exceptions, this role essentially allows the user full Studio access for their community. Known as Community Admin in Creator Studio.

Look here for the full permissions list of each of these roles plus more in Creator Studio.

Provision Publisher Role

Provisioning a user role can be done when creating a user or when editing one. By default, created users have the member role.

This example shows a user being created with the role of publisher. To provision a publisher role to a user, giving them access to Creator Studio, set role string enum value to publisher.

Endpoint

POST /scim/v2/users

This role is the equivilant of the Creator Studio content publisher role (refer here for further details). In short this gives the user access to content creating, publishing and Insights.

"roles": ["publisher"],

The same example expanded out:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "janeDoe123",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "externalId": "ext_123489",
  "nickName": "Jane",
  "active": true,
  "roles": ["publisher"],
  "phoneNumbers": [
    {
      "value": "555-1212",
      "type": "mobile",
      "primary": true
    }
  ],
  "emails": [
    {
      "value": "janedoe@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Mission St",
      "locality": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US",
      "primary": false,
      "formatted": "123 Mission St, San Francisco, CA, 94105",
      "type": "work"
    }
  ],
  "title": "Vice President",
  "photos": [
    {
      "type": "photo",
      "value": "http://an.image/url"
    }
  ],
  "preferredLanguage": "en-US",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",

Update User Role

Update or change a user's role (access and permissions) from a member with access to your community (employee experience only) to a higher role, such as content creator with access to Studio.

The user making the API call that changes a user's Firstup role needs the same level or higher role in Firstup themselves.

Only structured role objects (type/value) can be updated. String roles must be converted to object format to be modified.

This example shows an existing user's role being changed.

Endpoint

PATCH /scim/v2/users

To change this:

GET the user record using GET /scim/v2/Users/{user_id} to retrieve the user.
Copy the object and paste it into your PATCH request.
Create a replace operation (see example below).
Execute the PATCH request.

Replace operation request example for the role change:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "roles",
      "value": [
        {
          "type": "role",
          "value": "content_creator"
        }
      ]
    }
  ]
}

Refer to our SCIM Patching guide for more information on SCIM PATCH requests.

Scope

Sending a scope value will set the user's access permissions to topics, audiences, templates, email aliases and author aliases.

While roles determine the overall level of access (publisher, admin), scopes apply more granular restrictions, such as limiting access to specific topics, audiences, or templates. Making them a lower hierarchy in the permission structure.

If a scope isn't sent, the default value will be used, allowing the user total access (in line with their role).

Scope values (e.g. topic:todaynews) are not validated during submission, but they affect user access. Ensure they reference valid resources.

Example of setting a user's permissions in Creator Studio

Example of sending a user's permission via API

    "roles": [
        {
            "type": "role",
            "value": "community_admin"
        },
        {
            "type": "scope",
            "value": "topic:myfeed"
        },
        {
            "type": "scope",
            "value": "topic:holidayparty"
        },
        {
            "type": "scope",
            "value": "topic:businessnewsupdated!"
        }
        {
          "type": "scope",
          "value": "audience:123553345"
        }
        {
          "type": "scope",
          "value": "audience:43433455"
        }
    ],

Set User Permissions to Sales Dept

Assign a user role and user permissions to your user. For example, your user's role is publisher, but you only want to grant them access to topics and audiences relating to the sales department. These audiences and topics that relate to sales need to exist in order to send.

Set the roles object to include your chosen audiences and topics. In this example, the user's role is publisher and they have access to the sales-department audience and sales-department topic.

Endpoint

POST /scim/v2/users

Roles and Scope example

    "roles": [
        {
            "type": "role",
            "value": "publisher"
        },
        {
            "type": "scope",
            "value": "topic:sales-department"
        },
        {
            "type": "scope",
            "value": "audience:sales-department"
      
        }
    ]

Full example

The same example expanded out, to include what setting up a whole user looks like with our set scope:


{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "janeDoe123",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "externalId": "ext_123489",
  "nickName": "Jane",
  "active": true,
  "roles": [
    {
      "type": "role",
      "value": "publisher"
    },
    {
      "type": "scope",
      "value": "topic:sales-department"
    },
    {
      "type": "scope",
      "value": "audience:sales-department"
    }
  ],
  "phoneNumbers": [
    {
      "value": "555-1212",
      "type": "mobile",
      "primary": true
    }
  ],
  "emails": [
    {
      "value": "janedoe@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Mission St",
      "locality": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US",
      "primary": false,
      "formatted": "123 Mission St, San Francisco, CA, 94105",
      "type": "work"
    }
  ],
  "title": "Vice President",
  "photos": [
    {
      "type": "photo",
      "value": "http://an.image/url"
    }
  ],
  "preferredLanguage": "en-US",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago"
}

User Role Assigning

Role

Role String

Role Object

Get Available Roles

GET /scim/v2/roles

Provision Publisher Role

POST /scim/v2/users

Update User Role

PATCH /scim/v2/users

Scope

Set User Permissions to Sales Dept

POST /scim/v2/users

Was this helpful?