--- title: "createRole" method: POST path: "/v1/permissions/roles" tags: ["Roles"] --- # createRole `POST /v1/permissions/roles` Create role ## Request body - union - object — A standard user role. Must be explicitly assigned to users. - `grants` object[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - … - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - … - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - … - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - … - `id` string — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'user_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string — Id of an organization - `parent_role` string — Optional parent role that this role inherits from. Must be an `org_role` or a sharing role of type `share_role` or `partner_role`. - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization. - object — A role automatically applied to all users in an organization. - `grants` object[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - … - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - … - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - … - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - … - `id` string — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'org_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string — Id of an organization - `pricing_tier` string — The pricing tier of the organization this root role is based on - object — A role that can be assigned to users in other organizations for sharing purposes. - `grants` object[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - … - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - … - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - … - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - … - `id` string — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'share_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string — Id of an organization - object — A role that appears in another organization's role list that can be assigned but not modified by the partner organization. - `grants` object[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - … - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - … - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - … - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - … - `id` string — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'partner_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string — Id of an organization - `partner_org_id` string — Id of an organization - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization. - object — A role that is applied to end customers and installers using the Portals - `grants` object[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `dependencies` Grant[] — Provided additional dependencies, exploded when storing the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - … - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - … - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - … - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - … - `id` string — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'portal_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string — Id of an organization ## Response `200` ok - union - UserRole — A standard user role. Must be explicitly assigned to users. - `id` string, required — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'user_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string, required — Id of an organization - `grants` Grant[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `parent_role` string — Optional parent role that this role inherits from. Must be an `org_role` or `share_role`. - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization. - OrgRole — A role automatically applied to all users in an organization. - `id` string, required — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'org_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string, required — Id of an organization - `grants` Grant[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `pricing_tier` string — The pricing tier of the organization this root role is based on - ShareRole — A role that can be assigned to users in other organizations for sharing purposes. - `id` string, required — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'share_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string, required — Id of an organization - `grants` Grant[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - PartnerRole — A role that appears in another organization's role list that can be assigned but not modified by the partner organization. - `id` string, required — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'partner_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string, required — Id of an organization - `grants` Grant[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required - `partner_org_id` string — Id of an organization - `vendor_enforced_user_limit` integer — Maximum number of users that can be assigned this role (vendor-enforced limit, can only be set via internal auth) - `vendor_created` boolean — Indicates whether this role was created by a vendor organization on behalf of the partner organization. - PortalRole — A role that is applied to end customers and installers using the Portals - `id` string, required — Format: : - `name` string, required — Human-friendly name for the role - `slug` string, required — URL-friendly name for the role - `type` 'portal_role', required — Type of the role - `expires_at` string, date-time — date and time then the role will expire - `organization_id` string, required — Id of an organization - `grants` Grant[], required — List of grants (permissions) applied to the role - `action` string, required - `resource` string - `effect` 'allow' | 'deny' - `conditions` GrantCondition[] - union - object — Check if attribute equals to any of the values - `attribute` string, required - `operation` 'equals', required - `values` string[], required - object — Passes when the attribute does not equal any of the values. Records where the attribute is missing or empty pass the condition. - `attribute` string, required - `operation` 'not_equals', required - `values` string[], required - object — Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes when the current user appears in ANY of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'equals_current_user', required - object — Check if the current user is absent from the relation_user attributes on the entity. When attribute is provided, only that specific attribute path is checked. When attributes is provided, it takes precedence over attribute and the condition passes only when the current user appears in NONE of the listed attribute paths. - `attribute` string — Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned. - `attributes` string[] — Optional list of JSON paths to user attributes. Takes precedence over attribute. - `operation` 'not_equals_current_user', required ## Other responses - `400` — Invalid role configuration - `404` — Parent role does not exist ## Changes - **2026-08-27** `b29ea9adf72b` — 3 breaking, 16 info - the `allOf[#/components/schemas/BaseRoleForCreate]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCondition]/values` request property's minItems was increased to `1` - the `allOf[subschema #1]/grants/items/allOf[#/components/schemas/Grant]/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCondition]/values` request property's minItems was increased to `1` - the `allOf[subschema #1]/grants/items/allOf[subschema #2]/dependencies/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCondition]/values` request property's minItems was increased to `1` - added the new optional request property `allOf[#/components/schemas/BaseRoleForCreate]/grants/items/conditions/items/allOf[subschema #2]/anyOf[#/components/schemas/EqualsCurrentUserCondition]/attributes` - …15 more [Change history](https://skmtc.dev/epilot/apis/permissions-api/changes/v1/permissions/roles/post.md) --- [API](https://skmtc.dev/epilot/apis/permissions-api.md) · [All operations](https://skmtc.dev/epilot/apis/permissions-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/epilot/permissions-api/revisions/b29ea9adf72b/schema)