---
updatedAt: 2026-06-04T19:58:43.000Z
agentTools:
  projectIndex: https://docs.wristband.dev/llms.txt
---

# Create Role Assignment Policy

Creates the given role assignment policy.  If the `upsert` query param is set to `true` then, instead of performing a create, the API will switch to performing an upsert.  The following fields are required:

**Required Fields:**

* `ownerType`
* `ownerId`

When performing an upsert, the above fields will be used to determine whether the role assignment policy resource already exists.  If the role assignment policy already exists, a partial update will be performed; otherwise, a new role assignment policy entity will be created.

In the response of an upsert request, if a create was performed, then a `201` response code will be returned; otherwise, if an update was performed, then a `200` will be returned.

### Required Permissions

Below is the list of required permissions needed to interact with this API.  For each permission, the allowed permission boundaries are also specified.

| Permission                       | Boundary              | Description                                                                                                                         |
| -------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **role-assignment-policy:write** | Application           | The subject can create role assignment policies under the application that the subject belongs to.                                  |
|                                  | Tenant                | The subject can create role assignment policies for the tenant to which the subject belongs.                                        |
|                                  | Tenant Inclusion List | The subject can create role assignment policies for tenants specified in the tenant inclusion list.                                 |
|                                  | Tenant Exclusion List | The subject can create role assignment policies for tenants in the subject's application that are not on the tenant exclusion list. |

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Resource Management APIs",
    "version": "1.0.0",
    "description": "Resource Management APIs",
    "license": {
      "name": "Private",
      "url": "https://wristband.dev/terms/"
    },
    "termsOfService": "https://wristband.dev/terms/",
    "contact": {
      "name": "Wristband Support",
      "email": "support@wristband.dev",
      "url": "https://wristband.dev/contact/"
    }
  },
  "servers": [
    {
      "url": "https://{application_vanity_domain}",
      "description": "Wristband application scoped URL.",
      "variables": {
        "application_vanity_domain": {
          "default": "yourapp-yourorg.us.wristband.dev",
          "description": "Wristband vanity domain scoped to a specific application."
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Role Assignment Policies",
      "description": "Role Assignment Policies",
      "x-displayName": "Role Assignment Policies"
    }
  ],
  "paths": {
    "/api/v1/role-assignment-policies": {
      "post": {
        "summary": "Create Role Assignment Policy",
        "operationId": "createRoleAssignmentPolicyV1",
        "tags": [
          "Role Assignment Policies"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Resource_Management_APIs_Upsert"
          }
        ],
        "requestBody": {
          "description": "Role Assignment policy JSON object",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Resource_Management_APIs_RoleAssignmentPolicy"
              },
              "examples": {
                "Example 1 - Create Role Assignment Policy": {
                  "value": {
                    "ownerType": "APPLICATION",
                    "ownerId": "d7aml4q5lza3fdi2gavzdliouy",
                    "minimumLength": 12
                  }
                },
                "Example 2 - Upsert Role Assignment Policy": {
                  "value": {
                    "ownerType": "APPLICATION",
                    "ownerId": "d7aml4q5lza3fdi2gavzdliouy",
                    "minimumLength": 20
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/Resource_Management_APIs_ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource_Management_APIs_RoleAssignmentPolicy"
                },
                "examples": {
                  "Example 1 - Role Assignment Policy Created": {
                    "$ref": "#/components/examples/Resource_Management_APIs_RoleAssignmentPolicy"
                  }
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Resource_Management_APIs_Location"
              },
              "ETag": {
                "$ref": "#/components/headers/Resource_Management_APIs_ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource_Management_APIs_RoleAssignmentPolicy"
                },
                "examples": {
                  "Example 1 - Role Assignment Policy Created": {
                    "$ref": "#/components/examples/Resource_Management_APIs_RoleAssignmentPolicy"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Resource_Management_APIs_400-with-message-body"
          },
          "401": {
            "$ref": "#/components/responses/Resource_Management_APIs_401"
          },
          "403": {
            "$ref": "#/components/responses/Resource_Management_APIs_403"
          },
          "405": {
            "$ref": "#/components/responses/Resource_Management_APIs_405"
          },
          "406": {
            "$ref": "#/components/responses/Resource_Management_APIs_406"
          },
          "409": {
            "$ref": "#/components/responses/Resource_Management_APIs_409-upsert-conflict"
          },
          "415": {
            "$ref": "#/components/responses/Resource_Management_APIs_415"
          },
          "500": {
            "$ref": "#/components/responses/Resource_Management_APIs_500"
          },
          "503": {
            "$ref": "#/components/responses/Resource_Management_APIs_503"
          }
        },
        "security": [
          {
            "Resource_Management_APIs_BearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Resource_Management_APIs_BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "Resource_Management_APIs_Upsert": {
        "name": "upsert",
        "in": "query",
        "required": false,
        "schema": {
          "type": "boolean",
          "default": false
        },
        "description": "Boolean indicating if the operation should be treated as an upsert"
      }
    },
    "schemas": {
      "Resource_Management_APIs_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 26,
        "example": "pl4a4aa4jzydksmrf3jnu5yfcw",
        "description": "Globally unique Id of the resource.",
        "readOnly": true
      },
      "Resource_Management_APIs_api-error": {
        "title": "ApiError",
        "type": "object",
        "description": "API error object",
        "x-examples": {
          "Example 1": {
            "code": "invalid_request",
            "message": "The request was invalid",
            "ticket": "11t7n71hi5e6t"
          }
        },
        "properties": {
          "type": {
            "type": "string",
            "example": "base_error",
            "minLength": 1,
            "description": "The type of the API error.",
            "readOnly": true
          },
          "code": {
            "type": "string",
            "example": "invalid_request",
            "minLength": 1,
            "description": "A code identifying the error that occurred.",
            "readOnly": true
          },
          "message": {
            "type": "string",
            "example": "The request was invalid",
            "description": "A free text message describing the error.  This error message is only meant to help developers understand the cause of the error.  It should not be used for programmatic purposes.",
            "readOnly": true
          },
          "ticket": {
            "type": "string",
            "example": "11t7n71hi5e6t",
            "description": "Ticket that can help correlate the error to the backend",
            "readOnly": true
          },
          "details": {
            "type": "object",
            "description": "A map of details about the error. The keys are defined by the API.",
            "additionalProperties": {},
            "example": {
              "attemptsRemaining": 4
            }
          }
        },
        "required": [
          "type",
          "code"
        ]
      },
      "Resource_Management_APIs_constraint-violations-api-error": {
        "title": "ConstraintViolationsApiError",
        "description": "An API error that occurred due to a constraint violation",
        "allOf": [
          {
            "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
          },
          {
            "type": "object",
            "readOnly": true,
            "required": [
              "violations"
            ],
            "properties": {
              "violations": {
                "type": "object",
                "readOnly": true,
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "A code identifying the constraint violation.",
                    "minLength": 1,
                    "example": "too_long"
                  },
                  "constraintAttributes": {
                    "type": "object",
                    "description": "A map of constraint attribute values.",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "example": {
                      "maxLength": "10"
                    }
                  }
                }
              }
            }
          }
        ],
        "x-examples": {
          "Example 1": {
            "type": "constraint_violations_error",
            "code": "message_body_constraint_violations",
            "message": "The request contained invalid fields",
            "ticket": "11t7n71hi5e6t",
            "violations": {
              "field1": {
                "code": "too_long",
                "constraintAttributes": {
                  "maxLength": "10"
                }
              },
              "field2": {
                "code": "not_null"
              }
            }
          }
        }
      },
      "Resource_Management_APIs_upsertOwnerType": {
        "description": "[Required on Create and Upsert] The type of the owner of the resource.",
        "type": "string",
        "enum": [
          "APPLICATION",
          "TENANT"
        ],
        "minLength": 1,
        "maxLength": 30,
        "example": "APPLICATION"
      },
      "Resource_Management_APIs_upsertOwnerId": {
        "description": "[Required on Create and Upsert] The ID of the owner of the resource.",
        "type": "string",
        "minLength": 1,
        "maxLength": 26,
        "example": "d7aml4q5lza3fdi2gavzdliouy"
      },
      "Resource_Management_APIs_version-metadata": {
        "title": "VersionMetadata",
        "type": "object",
        "description": "Version metadata associated to a resource.",
        "properties": {
          "version": {
            "type": "string",
            "example": "1.0",
            "description": "The version of the resource",
            "readOnly": true
          },
          "lastModifiedTime": {
            "type": "string",
            "format": "date-time",
            "example": "2016-06-13T19:49:31.686Z",
            "description": "The time at which the resource was last modified",
            "readOnly": true
          },
          "creationTime": {
            "type": "string",
            "format": "date-time",
            "example": "2016-06-13T19:49:31.686Z",
            "description": "The time at which the resource was created",
            "readOnly": true
          }
        }
      },
      "Resource_Management_APIs_RoleAssignmentPolicy": {
        "title": "Role Assignment Policy",
        "description": "Role Assignment Policy",
        "type": "object",
        "x-tags": [
          "Models"
        ],
        "required": [
          "ownerType",
          "ownerId"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Resource_Management_APIs_id"
          },
          "ownerType": {
            "$ref": "#/components/schemas/Resource_Management_APIs_upsertOwnerType"
          },
          "ownerId": {
            "$ref": "#/components/schemas/Resource_Management_APIs_upsertOwnerId"
          },
          "defaultSignupRoles": {
            "description": "List of role IDs that will be assigned to a user upon signup.",
            "type": "array",
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "description": "ID of a role to assign.",
              "type": "string",
              "minLength": 1,
              "maxLength": 26,
              "example": "jayovsssgbgbpk47ihblujcm2e"
            },
            "example": [
              "jayovsssgbgbpk47ihblujcm2e"
            ]
          },
          "defaultIdpUserSyncRoles": {
            "description": "List of role IDs that will be assigned to a user when the user is synced from an external IdP.  This includes JIT provisioning flows and when roles are synced on login.  Note, the default roles  defined here will only be used if no other role assignments are specified that have higher precedence. For example, if IdP role mappings are defined for the user then the default roles will not be assigned.",
            "type": "array",
            "maxItems": 10,
            "uniqueItems": true,
            "items": {
              "description": "ID of a role to assign.",
              "type": "string",
              "minLength": 1,
              "maxLength": 26,
              "example": "nxa4sjc5rnhlrpaurknypfeqg4"
            },
            "example": [
              "nxa4sjc5rnhlrpaurknypfeqg4"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Resource_Management_APIs_version-metadata"
          }
        },
        "example": {
          "ownerType": "APPLICATION",
          "ownerId": "d7aml4q5lza3fdi2gavzdliouy",
          "defaultSignupRoles": [
            "jayovsssgbgbpk47ihblujcm2e"
          ],
          "defaultIdpUserSyncRoles": [
            "nxa4sjc5rnhlrpaurknypfeqg4"
          ]
        }
      }
    },
    "examples": {
      "Resource_Management_APIs_RoleAssignmentPolicy": {
        "description": "Basic example of a role assignment policy JSON object with all fields present.",
        "value": {
          "id": "a4jzydksmrf3jnu5yfcwpl4a4a",
          "ownerType": "APPLICATION",
          "ownerId": "d7aml4q5lza3fdi2gavzdliouy",
          "defaultSignupRoles": [
            "jayovsssgbgbpk47ihblujcm2e"
          ],
          "defaultIdpUserSyncRoles": [
            "nxa4sjc5rnhlrpaurknypfeqg4"
          ],
          "metadata": {
            "version": "0.0",
            "lastModifiedTime": "2021-06-13T19:49:31.686Z",
            "creationTime": "2021-06-13T19:49:31.686Z"
          }
        }
      }
    },
    "headers": {
      "Resource_Management_APIs_ETag": {
        "schema": {
          "type": "string",
          "example": "1.0",
          "minLength": 1
        },
        "description": "The version of the resource"
      },
      "Resource_Management_APIs_Location": {
        "schema": {
          "type": "string"
        },
        "description": "URL pointing to the location of the newly created resource"
      }
    },
    "responses": {
      "Resource_Management_APIs_401": {
        "description": "Unauthorized",
        "headers": {
          "WWW-Authenticate": {
            "description": "Includes details on the failed authentication condition. This header is set in accordance with the [OAuth2 specification](https://datatracker.ietf.org/doc/html/rfc6750#section-3).",
            "schema": {
              "type": "string",
              "example": "Bearer error=\"invalid_token\", error_description=\"The provided access token was invalid\""
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - unauthenticated": {
                "value": {
                  "type": "base_error",
                  "code": "invalid_access_token",
                  "message": "The provided access token was invalid",
                  "ticket": "1u0d0edhwbjsd"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_403": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - unauthorized": {
                "value": {
                  "type": "base_error",
                  "code": "unauthorized",
                  "message": "The request failed authorization",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_405": {
        "description": "Method Not Allowed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - method_not_supported": {
                "value": {
                  "type": "base_error",
                  "code": "method_not_supported",
                  "message": "The specified HTTP method is not supported",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_406": {
        "description": "Not Acceptable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - not_acceptable": {
                "value": {
                  "type": "base_error",
                  "code": "not_acceptable",
                  "message": "The Accept header was invalid",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_415": {
        "description": "Unsupported Media Type",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - unsupported_media_type": {
                "value": {
                  "type": "base_error",
                  "code": "unsupported_media_type",
                  "message": "The Content-Type header was invalid",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_500": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - internal_server_failure ": {
                "value": {
                  "type": "base_error",
                  "code": "internal_server_failure",
                  "message": "An unexpected error occurred while processing the request",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_503": {
        "description": "Service Unavailable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - service_unavailable": {
                "value": {
                  "type": "base_error",
                  "code": "service_unavailable",
                  "message": "The service is currently unavailable",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_400-with-message-body": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
                },
                {
                  "$ref": "#/components/schemas/Resource_Management_APIs_constraint-violations-api-error"
                }
              ]
            },
            "examples": {
              "code - invalid_request": {
                "value": {
                  "type": "base_error",
                  "code": "invalid_request",
                  "message": "The request was invalid",
                  "ticket": "11t7n71hi5e6t"
                }
              },
              "code - request_constraint_violations": {
                "value": {
                  "type": "constraint_violations_error",
                  "code": "message_body_constraint_violations",
                  "message": "The message body contained invalid fields",
                  "ticket": "11t7n71hi5e6t",
                  "violations": {
                    "field1": {
                      "code": "too_long",
                      "constraintAttributes": {
                        "maxLength": 10
                      }
                    },
                    "field2": {
                      "code": "not_null"
                    }
                  }
                }
              },
              "code - message_body_constraint_violations": {
                "value": {
                  "type": "constraint_violations_error",
                  "code": "message_body_constraint_violations",
                  "message": "The message body contained invalid fields",
                  "ticket": "11t7n71hi5e6t",
                  "violations": {
                    "field1": {
                      "code": "too_long",
                      "constraintAttributes": {
                        "maxLength": 10
                      }
                    },
                    "field2": {
                      "code": "not_null"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Resource_Management_APIs_409-upsert-conflict": {
        "description": "Conflict",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Resource_Management_APIs_api-error"
            },
            "examples": {
              "code - upsert_conflict": {
                "value": {
                  "type": "base_error",
                  "code": "upsert_conflict",
                  "message": "An upsert conflict occurred when attempting to upsert the resource",
                  "ticket": "11t7n71hi5e6t"
                }
              },
              "code - modification_conflict": {
                "value": {
                  "type": "base_error",
                  "code": "modification_conflict",
                  "message": "A modification conflict occurred when attempting to modify the resource",
                  "ticket": "11t7n71hi5e6t"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Resource Management APIs",
      "tags": [
        "Applications",
        "Auth Factors",
        "Auth Sessions",
        "Auth Session Policies",
        "Bot Detection Policies",
        "Custom Claims",
        "Custom Domains",
        "Email Brandings",
        "Email Domains",
        "Email Policies",
        "External IdP Profiles",
        "External IdP Tokens",
        "Identity Providers",
        "IdP Attribute Mappings",
        "IdP Role Mappings",
        "MFA Policies",
        "OAuth2 Clients",
        "Page Brandings",
        "Password Policies",
        "Permissions",
        "Permission Boundaries",
        "Permission Groups",
        "Refresh Tokens",
        "Remembered Tenants",
        "Roles",
        "Role Assignment Policies",
        "Signing Keys",
        "Tenants",
        "Users",
        "User Schemas",
        "Vanity Domains",
        "Webhook Policies",
        "Workflow Policies"
      ]
    }
  ]
}
```