create_role¶

ManagementApi.create_role(role_id, role_info, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Create a new access role

Creates a new access role. The caller automatically becomes a role manager, and every role manager is added to UsersAttached. The request body is validated against a strict allow-list: any property other than the six documented ones is rejected with IPV-1008. Role names must be unique and must not begin with the reserved prefix “SystemRole”. Not idempotent: a duplicate role name is rejected.

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. Not required when the request carries Super Admin context. (required)
role_info (RoleInfo) – (required)
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

RolesPostResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /roles

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`

Success (HTTP 200)¶

Role created. The body carries the new role’s identifier.

Request / response example

{
  "Message": "Successfully created the access role",
  "RoleId": "role-b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

Errors¶

Documented error codes: IPV-1008, IPV-1001, ROLE-1001, GE-1060, AUTH-1001, AUTH-1003, AUTH-1030, IPV-1002, DB-1001, DB-1002, GE-1008.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1008 (a required key is missing, or an unrecognised key was sent), IPV-1001 (RoleName is empty), ROLE-1001 (RoleName uses the reserved “SystemRole” prefix, or a permission is not recognised), GE-1060 (a user in UsersAttached or RoleManagers does not exist), AUTH-1001 / AUTH-1003 / AUTH-1030 / IPV-1002 (authorization).

A required key is absent from the body

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - {'RoleDescription'}"
}

Body contains a property outside the allow-list

{
  "Message": "IPV-1008 - Invalid request body, unsupported key(s) - {'Foo'}"
}

RoleName present but empty

{
  "Message": "IPV-1001 - Parameter RoleName is a required value."
}

RoleName uses the reserved SystemRole prefix

{
  "Message": "ROLE-1001 - Role name cannot start with SystemRole"
}

A user in UsersAttached does not exist

{
  "Message": "GE-1060 - User user9 is not valid user."
}

HTTP 500

Backend failure. Codes: DB-1001 / DB-1002 (the role or user profile could not be persisted), GE-1008 (generic). Body is {“Message”: “<CODE> - <text>”}.

Request / response example

{
  "Message": "DB-1001 - Failed to create the role"
}