Role

View as Markdown

Role

Role creates, fetches, lists, updates, and deletes the roles of a stack. A role is a set of rules and permissions that applies to every user who holds the role.

When to Use This Class: Use this class when your code manages access to a stack. For example, a setup script creates a Content Editor role that works on the main branch only.

Conceptual Role: Acts as the Content Management API (CMA) client for the /roles endpoint. Call stack.Role() to get an instance, and describe the role with a RoleModel object.

Returns: Role. A handle for role operations.

Instance State

The UID you pass to stack.Role() decides which methods you can call on the instance:

  • Call stack.Role() without a UID to work with the role collection, for example Query or Create.
  • Call stack.Role("<ROLE_UID>") to work with one role, for example Fetch or Delete.

If you call a method from the other group, it throws before any request leaves the SDK. A collection method on an instance that has a UID throws InvalidOperationException, and a single-item method on an instance with no UID throws ArgumentException.

The Method Index below lists every method in each group.

Warning The SDK checks for an empty string as if it were no UID, so stack.Role("") allows Query and Create, and the SDK then sends the request to /roles/ with a trailing slash. Pass null, or call stack.Role() with no argument, when you mean the collection.

Class-Level Notes

Authentication.

  • stack.Role() throws InvalidOperationException when the client has no authtoken and the Stack has no management token, and when the Stack has no API key.
  • When the Stack has a management token, the SDK sends it instead of the client's authtoken.
  • The CMA reference marks the authtoken header as required for the Create a role and Update role requests. Create the Stack without a management token before you call Create or Update.

Request body.

  • Create and Update serialize the RoleModel object under the role key. The SDK leaves out every property that is null.
  • Each rule in RoleModel.Rules goes out with the properties of its subclass, for example module and branches for a BranchRules object.

Errors.

  • The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.

Rate Limiting & Retry.

  • This SDK automatically retries a request that returns 429, 500, 502, 503, or 504, with configurable delay and attempt limits.

Additional Resources For more information on retry settings, refer to the ContentstackClientOptions documentation. For the request shapes, refer to the Roles section of the Content Management API reference.

Capability Matrix

CapabilitySupportedNotes / Alternative
Set rule permissions (acl) on a roleNoRule.ACL has no setter, so the SDK never sends it. Set permissions in the Contentstack web app.
Change a system roleNoThe API does not modify the system roles of a stack. Create a custom role instead.
Return the rules and permissions of a roleYesPass include_rules or include_permissions set to true in the collection of Fetch or of the query's Find.

Method Index

Work with the role collection. Available on stack.Role() when you pass no UID.

Method NameReturnsDescription
QueryA new query for roles.Builds a query that lists roles.
CreateThe API response with the created role.Creates a role.
CreateAsyncThe API response with the created role.Creates a role asynchronously.

Work with one role. Available on stack.Role("<ROLE_UID>").

Method NameReturnsDescription
FetchThe API response with the requested role.Retrieves one role.
FetchAsyncThe API response with the requested role.Retrieves one role asynchronously.
UpdateThe API response with the updated role.Changes the name, description, or rules of a role.
UpdateAsyncThe API response with the updated role.Changes a role asynchronously.
DeleteThe API response with the deletion notice.Deletes a role.
DeleteAsyncThe API response with the deletion notice.Deletes a role asynchronously.

Class-Level Snippet

The snippet below creates a Content Editor role for the main branch, then lists every role in the stack with its rules.

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");

RoleModel model = new RoleModel
{
    Name = "Content Editor",
    Description = "Edits content on the main branch",
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "$all" } }
    }
};

ParameterCollection collection = new ParameterCollection();
collection.Add("include_rules", true);

try
{
    ContentstackResponse created = await stack.Role().CreateAsync(model);
    Console.WriteLine($"New role UID: {created.OpenJsonObjectResponse()["role"]?["uid"]}");

    ContentstackResponse list = await stack.Role().Query().FindAsync(collection);
    Console.WriteLine(list.OpenJsonObjectResponse()["roles"]?.ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the Role class has its own section below, with its parameters, validation rules, behavior, and examples.

Create

Create creates a role in the stack from a RoleModel object.

NameTypeDescription
model (required)RoleModel

Name, description, and rules of the role.

Default: Not applicable
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the created role.

Validation

  • Throws InvalidOperationException if the instance has a UID, because Create adds a new role to the collection. Call stack.Role() with no UID.
  • Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
  • The SDK does not check model. A missing name or an unknown UID in the model reaches the API, and the SDK throws the API rejection as ContentstackErrorException. Read e.Errors for the property that the API rejected.
  • collection set to null sends no query parameters.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one POST request to /roles with the body {"role": <model>}. The SDK leaves out every RoleModel property that is null.
  • The Create a role request of the Content Management API reference describes the name, description, rules, and permissions that a role accepts. The reference marks the authtoken header as required for this request.
  • Returns the raw API response. The new role sits under the role key, and the API assigns its UID.

Known issue The SDK never sends the permissions (acl) of a rule, and every rule goes out with restrict set to false, because Rule.ACL and Rule.Restrict have no setter. A role that you create or update through RoleModel has rules without permissions. Set the permissions of the role in the Contentstack web app after you create or update it.

Example

Basic usage: create a role

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Content Editor",
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } }
    }
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role().Create(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: create a role with every property and a query parameter

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Blog Editor",
    Description = "Edits blog content on the main branch",
    DeployContent = false,
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "blog_post" } },
        new EnvironmentRules { Environments = new List<string> { "<ENVIRONMENT_NAME>" } }
    }
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role().Create(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: calling Create on an instance that has a UID

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel { Name = "Content Editor" };

try
{
    // Create works on the collection, so call stack.Role() with no UID.
    client.Stack("<API_KEY>").Role("<ROLE_UID>").Create(model);
}
catch (InvalidOperationException e)
{
    // Fires before any request, because the instance has a UID
    Console.WriteLine(e.Message);
}

CreateAsync

CreateAsync creates a role in the stack from a RoleModel object, without blocking the calling thread.

NameTypeDescription
model (required)RoleModel

Name, description, and rules of the role.

Default: Not applicable
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the created role.

Validation

  • Throws InvalidOperationException if the instance has a UID, because CreateAsync adds a new role to the collection. Call stack.Role() with no UID.
  • Throws ArgumentNullException (parameter dataModel) if model is null.
  • The SDK throws the exceptions above when you call CreateAsync, before it returns a task. An API rejection surfaces when you await the task, as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same POST request as Create, on a task that you await.
  • Otherwise behaves like Create.

Example

Basic usage: create a role

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Content Editor",
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } }
    }
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role().CreateAsync(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["uid"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: create a role with every property and a query parameter

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Blog Editor",
    Description = "Edits blog content on the main branch",
    DeployContent = false,
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "blog_post" } },
        new EnvironmentRules { Environments = new List<string> { "<ENVIRONMENT_NAME>" } }
    }
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role().CreateAsync(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Delete

Delete deletes the role whose UID you passed to stack.Role().

NameTypeDescription
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the deletion notice.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Delete removes one role. Call stack.Role("<ROLE_UID>").
  • The SDK does not check the UID format. A UID that names no role reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
  • collection set to null sends no query parameters.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one DELETE request to /roles/<ROLE_UID>, with the entries of collection as query parameters.
  • The Delete role request of the Content Management API reference deletes the role from the stack. The reference lists no query parameters for this request.
  • Returns the raw API response with a notice key.

Warning Deleting a role is permanent. The Content Management API reference lists no request that restores a deleted role.

Example

Basic usage: delete a role

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role("<ROLE_UID>").Delete();
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: delete a role with a query parameter collection, using a management token

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Role("<ROLE_UID>")
        .Delete(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeleteAsync

DeleteAsync deletes the role whose UID you passed to stack.Role(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the deletion notice.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because DeleteAsync removes one role. Call stack.Role("<ROLE_UID>").
  • The SDK throws the exception above when you call DeleteAsync, before it returns a task.
  • An API rejection surfaces when you await the task, as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same DELETE request as Delete, on a task that you await.
  • Otherwise behaves like Delete.

Warning Deleting a role is permanent. The Content Management API reference lists no request that restores a deleted role.

Example

Basic usage: delete a role

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role("<ROLE_UID>").DeleteAsync();
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: delete a role with a query parameter collection, using a management token

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Role("<ROLE_UID>")
        .DeleteAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Fetch

Fetch retrieves the role whose UID you passed to stack.Role().

NameTypeDescription
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the requested role.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Fetch reads one role. Call stack.Role("<ROLE_UID>").
  • The SDK does not check the UID format. A UID that names no role reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
  • collection set to null sends no query parameters.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one GET request to /roles/<ROLE_UID>, with the entries of collection as query parameters.
  • The Get a single role request of the Content Management API reference accepts query parameters on this request. include_permissions set to true adds the permissions of the role, and include_rules set to true adds its rules.
  • Returns the raw API response. The role sits under the role key. Read it as JSON with OpenJsonObjectResponse(), or deserialize the role node into a RoleModel object.

Example

Basic usage: fetch a role by UID

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role("<ROLE_UID>").Fetch();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a role with a query parameter, using a management token

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_rules", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Role("<ROLE_UID>")
        .Fetch(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["name"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Typed result: read the role into RoleModel

using System;
using System.Text.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role("<ROLE_UID>").Fetch();

    // The role sits under the "role" key, so deserialize that node.
    RoleModel? model = response.OpenJsonObjectResponse()["role"]?.Deserialize<RoleModel>(client.SerializerOptions);
    Console.WriteLine(model?.Name);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

FetchAsync

FetchAsync retrieves the role whose UID you passed to stack.Role(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the requested role.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because FetchAsync reads one role. Call stack.Role("<ROLE_UID>").
  • The SDK throws the exception above when you call FetchAsync, before it returns a task.
  • An API rejection surfaces when you await the task, as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same GET request as Fetch, on a task that you await.
  • Otherwise behaves like Fetch.

Example

Basic usage: fetch a role by UID

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role("<ROLE_UID>").FetchAsync();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: fetch a role with a query parameter, using a management token

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_rules", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Role("<ROLE_UID>")
        .FetchAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["name"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Query

Query returns a query object that lists the roles in the stack when you call Find or FindAsync on it.

This method takes no parameters.

Returns: Query. A new query for roles.

Validation

  • Throws InvalidOperationException if the instance has a UID, because Query lists the role collection. Call stack.Role() with no UID.
  • Query sends no request. Errors that do occur come from the Find or FindAsync call that follows, not from Query. The SDK throws an API rejection as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Find and FindAsync send one GET request to /roles. The request carries the parameters from Limit, Skip, IncludeCount, and the collection argument of Find. See the Query class for those methods.
  • The Get all roles request of the Content Management API reference accepts include_permissions, include_rules, and a query filter in JSON. Pass a filter with ParameterCollection.AddQuery.
  • Returns the raw API response. The roles sit under the roles key, and count holds the total when you call IncludeCount.
  • Does not page through the results for you. Without Limit and Skip, the API applies its own page size.

Example

Basic usage: list the roles in a stack

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role().Query().Find();
    JsonArray? items = response.OpenJsonObjectResponse()["roles"]?.AsArray();

    foreach (JsonNode? item in items ?? new JsonArray())
    {
        Console.WriteLine($"{item?["uid"]}: {item?["name"]}");
    }
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Paging: read one page of roles with a count, using a management token

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient();

ParameterCollection collection = new ParameterCollection();
collection.Add("include_rules", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .Role()
        .Query()
        .Limit(10)
        .Skip(0)
        .IncludeCount()
        .FindAsync(collection);
    Console.WriteLine($"Total roles: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Filter: find roles by name

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.AddQuery(new JsonObject { ["name"] = "Content Editor" });

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role().Query().Find(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["roles"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Update

Update changes the role whose UID you passed to stack.Role().

NameTypeDescription
model (required)RoleModel

The new values of the role.

Default: Not applicable
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: ContentstackResponse. The API response with the updated role.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Update changes one role. Call stack.Role("<ROLE_UID>").
  • Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
  • The SDK does not check model. An invalid value reaches the API, and the SDK throws the API rejection as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends one PUT request to /roles/<ROLE_UID> with the body {"role": <model>}. The SDK leaves out every RoleModel property that is null.
  • The Update role request of the Content Management API reference changes the role with the values you send. The API does not change the system roles that every stack has. The reference marks the authtoken header as required for this request.
  • Returns the raw API response. The updated role sits under the role key.

Known issue The SDK never sends the permissions (acl) of a rule, and every rule goes out with restrict set to false, because Rule.ACL and Rule.Restrict have no setter. A role that you create or update through RoleModel has rules without permissions. Set the permissions of the role in the Contentstack web app after you create or update it.

Example

Basic usage: update a role

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Content Editor",
    Description = "Edits all content on the main branch",
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "$all" } }
    }
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role("<ROLE_UID>").Update(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["name"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: update a role and add a query parameter

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Blog Editor",
    Description = "Edits blog content on the main branch",
    DeployContent = false,
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "blog_post" } },
        new EnvironmentRules { Environments = new List<string> { "<ENVIRONMENT_NAME>" } }
    }
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Role("<ROLE_UID>").Update(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

UpdateAsync

UpdateAsync changes the role whose UID you passed to stack.Role(), without blocking the calling thread.

NameTypeDescription
model (required)RoleModel

The new values of the role.

Default: Not applicable
collectionParameterCollection

Adds query parameters to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the updated role.

Validation

  • Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because UpdateAsync changes one role. Call stack.Role("<ROLE_UID>").
  • Throws ArgumentNullException (parameter dataModel) if model is null.
  • The SDK throws the exceptions above when you call UpdateAsync, before it returns a task. An API rejection surfaces when you await the task, as ContentstackErrorException.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends the same PUT request as Update, on a task that you await.
  • Otherwise behaves like Update.

Example

Basic usage: update a role

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Content Editor",
    Description = "Edits all content on the main branch",
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "$all" } }
    }
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role("<ROLE_UID>").UpdateAsync(model);
    Console.WriteLine(response.OpenJsonObjectResponse()["role"]?["name"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: update a role and add a query parameter

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

RoleModel model = new RoleModel
{
    Name = "Blog Editor",
    Description = "Edits blog content on the main branch",
    DeployContent = false,
    Rules = new List<Rule>
    {
        new BranchRules { Branches = new List<string> { "main" } },
        new ContentTypeRules { ContentTypes = new List<string> { "blog_post" } },
        new EnvironmentRules { Environments = new List<string> { "<ENVIRONMENT_NAME>" } }
    }
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Role("<ROLE_UID>").UpdateAsync(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}