# (NEW!) Create Security Role

Create a security role for the authenticated customer.

Business Rules:
- name must be 1-32 characters after trimming, and unique per customer, case-insensitively — enforced by a database constraint, so a race between two concurrent creates for the same name always resolves to exactly one winner and a 409 for the loser.
- Any field not in {name, consentForm, privileges} is rejected with 400.

Defaults:
- consentForm defaults to "". null is treated as absent.
- privileges defaults to []. Entries are de-duplicated case-insensitively.

Validation:
- Each privileges entry must be a syntactically valid UUID (400 if not), then must exist and be enabled in the customer's privilege catalog (422 if any id is unknown or disabled).

The user submitting the request must have the Role Management privilege.

Endpoint: POST /security/roles
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `X-API-Key` (string, required)
    Customer-specific API key required to invoke API.

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

  - `Content-Type` (string, required)
    Enum: "application/json"

## Request fields (application/json):

  - `name` (string, required)
    Display name of the role. 1-32 characters after trimming. Must be unique per customer, case-insensitively.
    Example: "Compression Engineer"

  - `consentForm` (string)
    Consent text a user must accept to hold this role. Defaults to an empty string. null is treated as absent.
    Example: "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm and follow all platform security policies."

  - `privileges` (array)
    Privilege ids to grant to the role. Defaults to []. De-duplicated case-insensitively. Each id must be a syntactically valid UUID and must exist and be enabled in the customer's privilege catalog.
    Example: ["31bdde6b-1a2c-4d5e-8f90-1234567890ab"]

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique ID of the role.
    Example: "6c15af83-d4a9-4772-875a-1c8a2bb1688f"

  - `name` (string, required)
    Display name of the role.
    Example: "Creative Producer"

  - `consentForm` (string)
    Consent text a user must accept to hold this role.
    Example: "By accepting this role you agree to uphold Pied Piper's brand and confidentiality guidelines when producing creative assets."

  - `privilegeCount` (integer)
    Number of privileges granted to the role.
    Example: 2

  - `privileges` (array)
    Flat array of permitted privilege ids only. Denied/unpermitted entries in the underlying role document are not surfaced.
    Example: ["31bdde6b-1a2c-4d5e-8f90-1234567890ab","9e187a4e-cfe4-419e-8c6c-2509e4bf400b"]

  - `userCount` (integer)
    Number of users currently assigned this role.
    Example: 12

  - `usedIn` (object)
    Everywhere the role is currently referenced.

  - `usedIn.presets` (array)
    Upload or filter presets whose role_ids include this role.

  - `usedIn.presets.id` (string)
    Example: "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f"

  - `usedIn.presets.name` (string)
    Example: "Pied Piper Marketing Upload"

  - `usedIn.presets.type` (string)
    Enum: "upload", "filter"

  - `createdBy` (string,null)
    User-profile id of the role's creator. null if the row has no recorded author.
    Example: "dc63db1b-1e63-43bc-877e-418931b6895c"

  - `createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1734000000000

  - `createdDate` (string,null)
    ISO 8601 creation date, derived from createdEpoch.
    Example: "2024-12-12T12:00:00.000Z"

  - `lastUpdatedBy` (string,null)
    User-profile id of the last user to update the role. null if the row has no recorded author.
    Example: "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec"

  - `lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1755600000000

  - `lastUpdatedDate` (string,null)
    ISO 8601 last-updated date, derived from lastUpdatedEpoch.
    Example: "2025-08-19T12:00:00.000Z"

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 409 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

  - `code` (string)
    Enum: "DUPLICATE_ROLE_NAME"

  - `details` (object)

  - `details.existingRoleId` (string)

## Response 422 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

  - `code` (string)
    Enum: "UNKNOWN_REFERENCES"

  - `details` (object)

  - `details.missingPrivilegeIds` (array)