> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/studio/integrations-and-apis/origin-studio-production-api/users.md).

# Users

This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant.

## Get multiple users

> Returns a paginated list of users for the caller's tenant. Results can be filtered by name, role, or status. The \`filter.status\` values are: \`active\` (verified and not blocked), \`pending\` (not yet verified), or \`deactivated\` (blocked). System users can additionally filter by a specific \`tenantId\` to retrieve users across tenants.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetUsersResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetUsersResponse","description":"Paginated response for listing users within a tenant. Each item in `data` is a full user resource with profile attributes and role relationships, plus a `meta.tenantId` and a self link. The top-level `meta` object provides total count and pagination offsets.","type":"object","additionalProperties":false,"required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","relationships"],"additionalProperties":false,"allOf":[{"$ref":"#/components/schemas/User"},{"type":"object","additionalProperties":false,"required":["meta","links"],"properties":{"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false}}}]},"additionalProperties":false},"meta":{"type":"object","properties":{"total":{"type":"integer"},"start":{"type":"integer"},"limit":{"type":"integer"}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A JSON:API user resource representing a person with access to Origin Studio. Includes profile attributes (email, name, picture, status) and relationships to the owning tenant and the user's assigned roles.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","const":"users"},"attributes":{"allOf":[{"$ref":"#/components/schemas/UserAttributes"}],"additionalProperties":false},"relationships":{"type":"object","required":["tenant"],"additionalProperties":false,"properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"roles":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleRelationship"}}}}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"JSON:API resource identifier. All Origin Studio API resource objects include at least an `id` (unique string identifier) and a `type` (the JSON:API resource type name, e.g. records, contributors).","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"UserAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserAttributes","description":"Attribute fields for a user. `source` distinguishes users created directly in Origin Studio (`local`) from those federated via an external identity provider (`external`). `blocked` indicates whether the user's access is disabled; when true the user cannot log in.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL to a picture for this user"},"name":{"type":"string","description":"Name of this user"},"email":{"type":"string","description":"Email address of this user"},"app_metadata":{"type":"object","description":"App-specific metadata for this user"},"source":{"type":"string","description":"Source of this user","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider used to authenticate this user (e.g. local, google-oauth2)"},"blocked":{"type":"boolean","description":"Whether the user is blocked/disabled"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"RoleRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationship","description":"A relationship to a role","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users":{"get":{"summary":"Get multiple users","description":"Returns a paginated list of users for the caller's tenant. Results can be filtered by name, role, or status. The `filter.status` values are: `active` (verified and not blocked), `pending` (not yet verified), or `deactivated` (blocked). System users can additionally filter by a specific `tenantId` to retrieve users across tenants.","operationId":"userFindMany","tags":["Users"],"parameters":[{"name":"page.size","description":"The number of results to return per page, default is 50","in":"query","required":false,"schema":{"type":"integer","default":50}},{"name":"page.number","description":"The page number to return, default is 0","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"filter.name","in":"query","required":false,"schema":{"type":"string"},"description":"Filter users by name. Example: filter.name=John Doe"},{"name":"filter.roles","in":"query","required":false,"style":"form","explode":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Filter users by roles. Example: filter.roles=Admin,Viewer"},{"name":"filter.status","in":"query","required":false,"schema":{"type":"string","enum":["active","pending","deactivated"]},"description":"Filter users by status. 'active' = verified and not blocked, 'pending' = not verified and not blocked, 'deactivated' = blocked. Example: filter.status=active"},{"name":"filter.tenant.id","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by tenant ID. Only available for system users."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUsersResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create users

> Create one or more users

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"CreateUsersRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ICreateUsersRequest","description":"Request body for creating one or more users in a single API call. Each entry in `data` specifies the user's email address and the role IDs to assign. The new user will receive an invitation email and must verify their account before logging in.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"The type of the resource, which must be 'user'"},"attributes":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The email address of the user"},"roles":{"type":"array","items":{"type":"string"},"description":"An array of role IDs to assign to the user"}},"required":["email","roles"],"additionalProperties":false}},"required":["type","attributes"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Optional audit metadata for a write request. `audit.source` is the issuing surface/channel (e.g. studio-web, mcp, api, system); `audit.reason` is a free-text justification. Both are optional and length-capped.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"CreateUsersResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ICreateUsersResponse","description":"Response returned by the batch user creation endpoint. The `data` object contains separate `created` and `failed` arrays, allowing partial success — the caller should inspect both arrays even on a 201 response.","type":"object","properties":{"data":{"type":"object","$ref":"#/components/schemas/CreateUsersData"}},"required":["data"],"additionalProperties":false},"CreateUsersData":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ICreateUsersData","description":"The result payload of a batch user creation operation. `created` lists users that were successfully created with their email and assigned role IDs. `failed` lists entries that could not be created, each with the email address, HTTP status code, and error details explaining the failure.","type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"id":{"type":"string","format":"email"},"attributes":{"type":"object","properties":{"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"type":"string"}}},"required":["email","roles"]}},"required":["type","id","attributes"],"additionalProperties":false}},"failed":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"status":{"type":"number"},"title":{"type":"string"},"detail":{"type":"string"}},"required":["email","status","title","detail"],"additionalProperties":false}}},"required":["created","failed"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users":{"post":{"summary":"Create users","description":"Create one or more users","operationId":"userCreateMany","tags":["Users"],"parameters":[{"name":"tenantId","description":"The ID of the tenant to create users for","in":"query","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUsersRequest"}}},"required":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUsersResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a user by ID

> Returns a single user's profile and role assignments by their unique ID, scoped to the caller's tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"GetUserResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetUserResponse","description":"The response for a user find one request.","type":"object","additionalProperties":false,"required":["data","meta","links"],"properties":{"data":{"$ref":"#/components/schemas/User"},"meta":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"},"permissions":{"type":"object","properties":{"deliveryWorkspace":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","properties":{"write":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","properties":{"canAccess":{"type":"boolean"}}}}}}}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A JSON:API user resource representing a person with access to Origin Studio. Includes profile attributes (email, name, picture, status) and relationships to the owning tenant and the user's assigned roles.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","const":"users"},"attributes":{"allOf":[{"$ref":"#/components/schemas/UserAttributes"}],"additionalProperties":false},"relationships":{"type":"object","required":["tenant"],"additionalProperties":false,"properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"roles":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleRelationship"}}}}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"JSON:API resource identifier. All Origin Studio API resource objects include at least an `id` (unique string identifier) and a `type` (the JSON:API resource type name, e.g. records, contributors).","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"UserAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserAttributes","description":"Attribute fields for a user. `source` distinguishes users created directly in Origin Studio (`local`) from those federated via an external identity provider (`external`). `blocked` indicates whether the user's access is disabled; when true the user cannot log in.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL to a picture for this user"},"name":{"type":"string","description":"Name of this user"},"email":{"type":"string","description":"Email address of this user"},"app_metadata":{"type":"object","description":"App-specific metadata for this user"},"source":{"type":"string","description":"Source of this user","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider used to authenticate this user (e.g. local, google-oauth2)"},"blocked":{"type":"boolean","description":"Whether the user is blocked/disabled"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"RoleRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationship","description":"A relationship to a role","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/{userId}":{"get":{"summary":"Get a user by ID","description":"Returns a single user's profile and role assignments by their unique ID, scoped to the caller's tenant.","operationId":"userFindOne","tags":["Users"],"parameters":[{"name":"userId","description":"The ID of the user to retrieve","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a user

> Delete a user by ID

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}}},"paths":{"/users/{userId}":{"delete":{"summary":"Delete a user","description":"Delete a user by ID","operationId":"userDeleteOne","tags":["Users"],"parameters":[{"name":"userId","description":"The ID of the user to delete","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"}}}}}}
```

## Update a user

> Updates an existing user's profile or role assignments. Supports partial updates via JSON:API patch semantics — only the fields included in the request are changed. Returns the updated user in the response.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"PatchUserRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IPatchUserRequest","description":"Request body for partially updating a user. Supports updating the user's `blocked` status via `attributes` and/or replacing the user's role assignments via `relationships.roles`. The `data.id` must match the `userId` path parameter.","type":"object","required":["data"],"additionalProperties":false,"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"required":["id","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["users"]},"attributes":{"type":"object","additionalProperties":false,"properties":{"blocked":{"type":"boolean"}}},"relationships":{"type":"object","required":["roles"],"additionalProperties":false,"properties":{"roles":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]}}}}}}}}}}]}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Optional audit metadata for a write request. `audit.source` is the issuing surface/channel (e.g. studio-web, mcp, api, system); `audit.reason` is a free-text justification. Both are optional and length-capped.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"JSON:API resource identifier. All Origin Studio API resource objects include at least an `id` (unique string identifier) and a `type` (the JSON:API resource type name, e.g. records, contributors).","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"GetUserResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetUserResponse","description":"The response for a user find one request.","type":"object","additionalProperties":false,"required":["data","meta","links"],"properties":{"data":{"$ref":"#/components/schemas/User"},"meta":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"},"permissions":{"type":"object","properties":{"deliveryWorkspace":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","properties":{"write":{"type":"object","properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","properties":{"canAccess":{"type":"boolean"}}}}}}}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A JSON:API user resource representing a person with access to Origin Studio. Includes profile attributes (email, name, picture, status) and relationships to the owning tenant and the user's assigned roles.","allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","const":"users"},"attributes":{"allOf":[{"$ref":"#/components/schemas/UserAttributes"}],"additionalProperties":false},"relationships":{"type":"object","required":["tenant"],"additionalProperties":false,"properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"roles":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleRelationship"}}}}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"UserAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserAttributes","description":"Attribute fields for a user. `source` distinguishes users created directly in Origin Studio (`local`) from those federated via an external identity provider (`external`). `blocked` indicates whether the user's access is disabled; when true the user cannot log in.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL to a picture for this user"},"name":{"type":"string","description":"Name of this user"},"email":{"type":"string","description":"Email address of this user"},"app_metadata":{"type":"object","description":"App-specific metadata for this user"},"source":{"type":"string","description":"Source of this user","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider used to authenticate this user (e.g. local, google-oauth2)"},"blocked":{"type":"boolean","description":"Whether the user is blocked/disabled"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"RoleRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationship","description":"A relationship to a role","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/{userId}":{"patch":{"summary":"Update a user","description":"Updates an existing user's profile or role assignments. Supports partial updates via JSON:API patch semantics — only the fields included in the request are changed. Returns the updated user in the response.","operationId":"userUpdateOne","tags":["Users"],"parameters":[{"name":"userId","description":"The ID of the user to update","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchUserRequest"}}},"required":true},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a user's roles

> Returns the roles assigned to the specified user as a related-resource collection. Supports the \`me\` alias for the current caller. You can always read your own roles; reading another user requires permission to read that user, and that user must belong to your tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"RoleFindManyResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleFindManyResponse","description":"Response for listing all roles in a tenant. Each item in `data` is a full role resource with its name, description, dataSource, timestamps, tenant relationship, and author relationship. The `meta.tenantId` on each role item identifies the owning tenant.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]},"attributes":{"allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"$ref":"#/components/schemas/UserRoleAttributes"}]},"relationships":{"$ref":"#/components/schemas/RoleRelationships"},"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]},"links":{"$ref":"#/components/schemas/LinksRelated"}}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Common timestamps present on all resource attribute objects. `created` is the ISO 8601 date-time when the resource was first created; `updated` is the date-time of the most recent modification.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"UserRoleAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRoleAttributes","description":"Attributes of a user role. `name` is the display name (e.g., 'Admin', 'Editor'). `dataSource` indicates whether the role is system-provisioned by Fabric (`fabric`) or created by the tenant (`custom`). Fabric roles cannot be renamed or deleted.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Name of this role"},"description":{"type":"string","description":"Description of this role"},"dataSource":{"type":"string","description":"The data source of the role","enum":["custom","fabric"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"RoleRelationships":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationships","description":"JSON:API relationship links for a role resource. Contains the owning `tenant` relationship and an optional `author` relationship identifying the user who created the role (with display name and tenant context in meta).","type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","required":["tenantId","type","displayName"],"properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"additionalProperties":false}}}},"required":["tenant"],"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/{userId}/roles":{"get":{"summary":"Get a user's roles","description":"Returns the roles assigned to the specified user as a related-resource collection. Supports the `me` alias for the current caller. You can always read your own roles; reading another user requires permission to read that user, and that user must belong to your tenant.","operationId":"userRolesFindMany","tags":["Users"],"parameters":[{"name":"userId","description":"The ID of the user whose roles to retrieve, or `me` for the current caller","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindManyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a user's effective permissions

> Returns a descriptive, human-readable summary of what the specified user is allowed to do, aggregated across all of their roles. Synthesised from the static system-role baseline plus the custom policies assigned to those roles (no live authorization evaluation). Supports the \`me\` alias for the current caller. You can always read your own permissions; reading another user requires permission to read that user, and that user must belong to your tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"EffectivePermissionsResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsResponse","description":"Effective permissions for a user (the union of their roles, via /users/{userId}/permissions) or a single role (via /roles/{roleId}/permissions). The two endpoints share this structurally identical shape.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["effectivePermissions"]},"attributes":{"$ref":"#/components/schemas/EffectivePermissionsAttributes"},"meta":{"type":"object","additionalProperties":false,"required":["tenantId"],"properties":{"tenantId":{"type":"string"}}}}},"links":{"type":"object","additionalProperties":false,"required":["self"],"properties":{"self":{"type":"string"}}}}},"EffectivePermissionsAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsAttributes","description":"Descriptive summary of what a role (or the union of a user's roles) is allowed to do.","type":"object","additionalProperties":false,"required":["roles","fullAccess","resourceGroups"],"properties":{"roles":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["roleId","isSystemRole"],"properties":{"roleId":{"type":"string"},"roleName":{"type":"string"},"isSystemRole":{"type":"boolean"}}}},"fullAccess":{"type":"boolean","description":"True when the role is unrestricted within 'scope'. When true, 'resourceGroups' is empty."},"scope":{"type":"string","enum":["global","tenant"],"description":"Present when 'fullAccess' is true. Indicates the breadth of that unrestricted access: 'tenant' covers the caller's own tenant."},"forbids":{"type":"array","items":{"type":"string"},"description":"Stable keys describing notable restrictions (Admin caveats)."},"resourceGroups":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveResourceGroup"}}}},"EffectiveResourceGroup":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveResourceGroup","description":"All allowed actions on a single resource category.","type":"object","additionalProperties":false,"required":["resourceType","grants"],"properties":{"resourceType":{"type":"string","enum":["record","contributor","credits","media","delivery","dataset","field","recordLayout","recordLifecycle","tenant","user","globalMetadata","bulkActions"]},"grants":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveActionGrant"}}}},"EffectiveActionGrant":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveActionGrant","description":"A single allowed action on a resource, tagged with where it comes from.","type":"object","additionalProperties":false,"required":["verb","source"],"properties":{"verb":{"type":"string","enum":["Create","Read","Update","Delete","Write"],"description":"The allowed action verb."},"source":{"type":"string","enum":["baseline","policy"],"description":"'baseline' = granted by the role's identity (system policies); 'policy' = a custom assigned policy."},"policyId":{"type":"string"},"templateId":{"type":"string"},"templateLabel":{"type":"string"},"conditions":{"$ref":"#/components/schemas/EffectiveConditions"}}},"EffectiveConditions":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveConditions","description":"Scoping conditions attached to a policy-granted action. Mirrors the policy template's conditions. Only present on grants with source 'policy'.","type":"object","additionalProperties":false,"properties":{"workTypes":{"type":"array","items":{"type":"string"}},"locales":{"type":"array","items":{"type":"string"}},"lifecyclePhases":{"type":"array","items":{"type":"string"}},"lifecycleStatuses":{"type":"object","description":"Per-work-type lifecycle status access (the template's workTypeLifecycleAccess). Keyed by work type because status ids are only unique within a work type.","additionalProperties":{"type":"array","items":{"type":"string"}}},"sectionIds":{"type":"array","items":{"type":"string"}},"createSources":{"type":"array","items":{"type":"string"}},"updateTypes":{"type":"array","items":{"type":"string"}},"securityTagId":{"type":"string"},"dataGroups":{"type":"object","description":"Per-work-type entity-collection access (the template's workTypeEntityAccess).","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"creditsAccess":{"type":"boolean"},"mediaAccess":{"type":"array","items":{"type":"string"}},"externalDataAccess":{"type":"boolean"}}}}}},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/{userId}/permissions":{"get":{"summary":"Get a user's effective permissions","description":"Returns a descriptive, human-readable summary of what the specified user is allowed to do, aggregated across all of their roles. Synthesised from the static system-role baseline plus the custom policies assigned to those roles (no live authorization evaluation). Supports the `me` alias for the current caller. You can always read your own permissions; reading another user requires permission to read that user, and that user must belong to your tenant.","operationId":"userPermissionsFindOne","tags":["Users"],"parameters":[{"name":"userId","description":"The ID of the user whose permissions to retrieve, or `me` for the current caller","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectivePermissionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get the roles for a tenant

> Returns all Roles defined for the caller's tenant, including system-provisioned roles (Admin, Editor, Viewer) and any user-created custom roles. Results can be filtered by role name.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"RoleFindManyResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleFindManyResponse","description":"Response for listing all roles in a tenant. Each item in `data` is a full role resource with its name, description, dataSource, timestamps, tenant relationship, and author relationship. The `meta.tenantId` on each role item identifies the owning tenant.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","type","attributes","relationships","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]},"attributes":{"allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"$ref":"#/components/schemas/UserRoleAttributes"}]},"relationships":{"$ref":"#/components/schemas/RoleRelationships"},"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]},"links":{"$ref":"#/components/schemas/LinksRelated"}}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Common timestamps present on all resource attribute objects. `created` is the ISO 8601 date-time when the resource was first created; `updated` is the date-time of the most recent modification.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"UserRoleAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRoleAttributes","description":"Attributes of a user role. `name` is the display name (e.g., 'Admin', 'Editor'). `dataSource` indicates whether the role is system-provisioned by Fabric (`fabric`) or created by the tenant (`custom`). Fabric roles cannot be renamed or deleted.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Name of this role"},"description":{"type":"string","description":"Description of this role"},"dataSource":{"type":"string","description":"The data source of the role","enum":["custom","fabric"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"RoleRelationships":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationships","description":"JSON:API relationship links for a role resource. Contains the owning `tenant` relationship and an optional `author` relationship identifying the user who created the role (with display name and tenant context in meta).","type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","required":["tenantId","type","displayName"],"properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"additionalProperties":false}}}},"required":["tenant"],"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles":{"get":{"summary":"Get the roles for a tenant","description":"Returns all Roles defined for the caller's tenant, including system-provisioned roles (Admin, Editor, Viewer) and any user-created custom roles. Results can be filtered by role name.","operationId":"roleFindMany","tags":["Users"],"parameters":[{"name":"filter.name","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"string"},"description":"Filter roles by name. Example: filter.name=MyRole"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindManyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a role

> Creates a new custom Role for the caller's tenant. Custom roles can be assigned Security Policies to define granular access control. System roles (Admin, Editor, Viewer) are pre-provisioned and cannot be created via this endpoint.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"CreateRoleRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleCreateRequest","description":"Request body for creating a new custom role in a tenant. The `name` is required and must be unique within the tenant. An optional `description` can be provided to explain the role's purpose.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/BaseCreateRequest"},{"additionalProperties":false,"properties":{"attributes":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The name of the role"},"description":{"type":"string","description":"The description of the role"}}}},"required":["attributes"]}]}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Optional audit metadata for a write request. `audit.source` is the issuing surface/channel (e.g. studio-web, mcp, api, system); `audit.reason` is a free-text justification. Both are optional and length-capped.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"BaseCreateRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseCreateRequest","description":"Base JSON:API shape for create requests. The `type` field is required and must match the target resource type. The `id` field is optional; if omitted, the server generates a unique ID for the new resource.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["type"]},"RoleFindOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleFindOneResponse","description":"The response for a user role find one request.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]},"attributes":{"allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"$ref":"#/components/schemas/UserRoleAttributes"}]},"relationships":{"$ref":"#/components/schemas/RoleRelationships"},"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Common timestamps present on all resource attribute objects. `created` is the ISO 8601 date-time when the resource was first created; `updated` is the date-time of the most recent modification.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"UserRoleAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRoleAttributes","description":"Attributes of a user role. `name` is the display name (e.g., 'Admin', 'Editor'). `dataSource` indicates whether the role is system-provisioned by Fabric (`fabric`) or created by the tenant (`custom`). Fabric roles cannot be renamed or deleted.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Name of this role"},"description":{"type":"string","description":"Description of this role"},"dataSource":{"type":"string","description":"The data source of the role","enum":["custom","fabric"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"RoleRelationships":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationships","description":"JSON:API relationship links for a role resource. Contains the owning `tenant` relationship and an optional `author` relationship identifying the user who created the role (with display name and tenant context in meta).","type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","required":["tenantId","type","displayName"],"properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"additionalProperties":false}}}},"required":["tenant"],"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles":{"post":{"summary":"Create a role","description":"Creates a new custom Role for the caller's tenant. Custom roles can be assigned Security Policies to define granular access control. System roles (Admin, Editor, Viewer) are pre-provisioned and cannot be created via this endpoint.","operationId":"roleCreateOne","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoleRequest"}}},"required":true},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindOneResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a role's effective permissions

> Returns a descriptive, human-readable summary of what a role is allowed to do, synthesised from the static system-role baseline plus the custom policies assigned to the role. Intended for admins previewing a role's access. Requires permission to read policies.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"EffectivePermissionsResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsResponse","description":"Effective permissions for a user (the union of their roles, via /users/{userId}/permissions) or a single role (via /roles/{roleId}/permissions). The two endpoints share this structurally identical shape.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"object","required":["id","type","attributes"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["effectivePermissions"]},"attributes":{"$ref":"#/components/schemas/EffectivePermissionsAttributes"},"meta":{"type":"object","additionalProperties":false,"required":["tenantId"],"properties":{"tenantId":{"type":"string"}}}}},"links":{"type":"object","additionalProperties":false,"required":["self"],"properties":{"self":{"type":"string"}}}}},"EffectivePermissionsAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsAttributes","description":"Descriptive summary of what a role (or the union of a user's roles) is allowed to do.","type":"object","additionalProperties":false,"required":["roles","fullAccess","resourceGroups"],"properties":{"roles":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["roleId","isSystemRole"],"properties":{"roleId":{"type":"string"},"roleName":{"type":"string"},"isSystemRole":{"type":"boolean"}}}},"fullAccess":{"type":"boolean","description":"True when the role is unrestricted within 'scope'. When true, 'resourceGroups' is empty."},"scope":{"type":"string","enum":["global","tenant"],"description":"Present when 'fullAccess' is true. Indicates the breadth of that unrestricted access: 'tenant' covers the caller's own tenant."},"forbids":{"type":"array","items":{"type":"string"},"description":"Stable keys describing notable restrictions (Admin caveats)."},"resourceGroups":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveResourceGroup"}}}},"EffectiveResourceGroup":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveResourceGroup","description":"All allowed actions on a single resource category.","type":"object","additionalProperties":false,"required":["resourceType","grants"],"properties":{"resourceType":{"type":"string","enum":["record","contributor","credits","media","delivery","dataset","field","recordLayout","recordLifecycle","tenant","user","globalMetadata","bulkActions"]},"grants":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveActionGrant"}}}},"EffectiveActionGrant":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveActionGrant","description":"A single allowed action on a resource, tagged with where it comes from.","type":"object","additionalProperties":false,"required":["verb","source"],"properties":{"verb":{"type":"string","enum":["Create","Read","Update","Delete","Write"],"description":"The allowed action verb."},"source":{"type":"string","enum":["baseline","policy"],"description":"'baseline' = granted by the role's identity (system policies); 'policy' = a custom assigned policy."},"policyId":{"type":"string"},"templateId":{"type":"string"},"templateLabel":{"type":"string"},"conditions":{"$ref":"#/components/schemas/EffectiveConditions"}}},"EffectiveConditions":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveConditions","description":"Scoping conditions attached to a policy-granted action. Mirrors the policy template's conditions. Only present on grants with source 'policy'.","type":"object","additionalProperties":false,"properties":{"workTypes":{"type":"array","items":{"type":"string"}},"locales":{"type":"array","items":{"type":"string"}},"lifecyclePhases":{"type":"array","items":{"type":"string"}},"lifecycleStatuses":{"type":"object","description":"Per-work-type lifecycle status access (the template's workTypeLifecycleAccess). Keyed by work type because status ids are only unique within a work type.","additionalProperties":{"type":"array","items":{"type":"string"}}},"sectionIds":{"type":"array","items":{"type":"string"}},"createSources":{"type":"array","items":{"type":"string"}},"updateTypes":{"type":"array","items":{"type":"string"}},"securityTagId":{"type":"string"},"dataGroups":{"type":"object","description":"Per-work-type entity-collection access (the template's workTypeEntityAccess).","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"creditsAccess":{"type":"boolean"},"mediaAccess":{"type":"array","items":{"type":"string"}},"externalDataAccess":{"type":"boolean"}}}}}},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles/{roleId}/permissions":{"get":{"summary":"Get a role's effective permissions","description":"Returns a descriptive, human-readable summary of what a role is allowed to do, synthesised from the static system-role baseline plus the custom policies assigned to the role. Intended for admins previewing a role's access. Requires permission to read policies.","operationId":"rolePermissionsFindOne","tags":["Users"],"parameters":[{"name":"roleId","description":"The ID of the role","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectivePermissionsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a role

> Returns a single Role by its unique ID, scoped to the caller's tenant. Includes the role's name, description, and associated security policies.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"RoleFindOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleFindOneResponse","description":"The response for a user role find one request.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]},"attributes":{"allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"$ref":"#/components/schemas/UserRoleAttributes"}]},"relationships":{"$ref":"#/components/schemas/RoleRelationships"},"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Common timestamps present on all resource attribute objects. `created` is the ISO 8601 date-time when the resource was first created; `updated` is the date-time of the most recent modification.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"UserRoleAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRoleAttributes","description":"Attributes of a user role. `name` is the display name (e.g., 'Admin', 'Editor'). `dataSource` indicates whether the role is system-provisioned by Fabric (`fabric`) or created by the tenant (`custom`). Fabric roles cannot be renamed or deleted.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Name of this role"},"description":{"type":"string","description":"Description of this role"},"dataSource":{"type":"string","description":"The data source of the role","enum":["custom","fabric"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"RoleRelationships":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationships","description":"JSON:API relationship links for a role resource. Contains the owning `tenant` relationship and an optional `author` relationship identifying the user who created the role (with display name and tenant context in meta).","type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","required":["tenantId","type","displayName"],"properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"additionalProperties":false}}}},"required":["tenant"],"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles/{roleId}":{"get":{"summary":"Get a role","description":"Returns a single Role by its unique ID, scoped to the caller's tenant. Includes the role's name, description, and associated security policies.","operationId":"roleFindOne","tags":["Users"],"parameters":[{"name":"roleId","description":"The ID of the role to get","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindOneResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a role

> Permanently deletes a custom Role by its unique ID. Users who had this role assigned will lose the associated permissions. System roles (Admin, Editor, Viewer) cannot be deleted.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"WriteMetaOnlyRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteMetaOnlyRequest","description":"Optional request body carrying only audit metadata, used by mutations that otherwise take no body (e.g. resource DELETEs). Lets clients attach meta.audit.source/reason to such operations. The body itself is optional; it is not otherwise required.","type":"object","additionalProperties":false,"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Optional audit metadata for a write request. `audit.source` is the issuing surface/channel (e.g. studio-web, mcp, api, system); `audit.reason` is a free-text justification. Both are optional and length-capped.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles/{roleId}":{"delete":{"summary":"Delete a role","description":"Permanently deletes a custom Role by its unique ID. Users who had this role assigned will lose the associated permissions. System roles (Admin, Editor, Viewer) cannot be deleted.","operationId":"roleDeleteOne","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteMetaOnlyRequest"}}}},"tags":["Users"],"parameters":[{"name":"roleId","description":"The ID of the role to delete","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a role

> Updates an existing Role by its unique ID. Supports partial updates — only the fields included in the request body are modified. System roles cannot be renamed. The updated role is returned in the response.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2264"},"tags":[{"name":"Users","description":"This API provides a way to manage Users and Roles in the context of a Tenant. A User is commonly used to represent a person, but in the future it may also represent a non-human entity such as an automated system. A Role is a collection of Security Policies which are used to determine what a User can do within a Tenant."}],"servers":[{"url":"{protocol}://{domain}/{basePath}","variables":{"protocol":{"enum":["http","https"],"default":"https"},"domain":{"default":"api.studio.fabricdata.com"},"basePath":{"default":"v1"}}}],"security":[{"jwt-apikey-authorizer":[]}],"components":{"securitySchemes":{"jwt-apikey-authorizer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"RoleUpdateOneRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleUpdateOneRequest","description":"Request body for updating a role's description. Currently only the `description` attribute is updatable via this endpoint. The role name is immutable after creation.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"additionalProperties":false,"properties":{"attributes":{"type":"object","required":["description"],"additionalProperties":false,"properties":{"description":{"type":"string","description":"The description of the role"}}}},"required":["attributes"]}]}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Optional audit metadata for a write request. `audit.source` is the issuing surface/channel (e.g. studio-web, mcp, api, system); `audit.reason` is a free-text justification. Both are optional and length-capped.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"JSON:API resource identifier. All Origin Studio API resource objects include at least an `id` (unique string identifier) and a `type` (the JSON:API resource type name, e.g. records, contributors).","type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}},"required":["id","type"],"additionalProperties":false},"RoleUpdateOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleUpdateOneResponse","description":"The response for a user role update one request.","type":"object","additionalProperties":false,"required":["data","links"],"properties":{"data":{"type":"object","required":["id","type","attributes","relationships","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userRoles"]},"attributes":{"allOf":[{"$ref":"#/components/schemas/BaseResourceAttributes"},{"$ref":"#/components/schemas/UserRoleAttributes"}]},"relationships":{"$ref":"#/components/schemas/RoleRelationships"},"meta":{"type":"object","properties":{"tenantId":{"type":"string"}},"required":["tenantId"]}}},"links":{"type":"object","required":["self"],"properties":{"self":{"type":"string"}},"additionalProperties":false}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Common timestamps present on all resource attribute objects. `created` is the ISO 8601 date-time when the resource was first created; `updated` is the date-time of the most recent modification.","type":"object","additionalProperties":false,"required":["created","updated"],"properties":{"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"UserRoleAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserRoleAttributes","description":"Attributes of a user role. `name` is the display name (e.g., 'Admin', 'Editor'). `dataSource` indicates whether the role is system-provisioned by Fabric (`fabric`) or created by the tenant (`custom`). Fabric roles cannot be renamed or deleted.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Name of this role"},"description":{"type":"string","description":"Description of this role"},"dataSource":{"type":"string","description":"The data source of the role","enum":["custom","fabric"]},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"RoleRelationships":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IRoleRelationships","description":"JSON:API relationship links for a role resource. Contains the owning `tenant` relationship and an optional `author` relationship identifying the user who created the role (with display name and tenant context in meta).","type":"object","properties":{"tenant":{"$ref":"#/components/schemas/TenantRelationship"},"author":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["id","type","meta"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["users"]},"meta":{"type":"object","required":["tenantId","type","displayName"],"properties":{"tenantId":{"type":"string"},"type":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"links":{"type":"object","properties":{"related":{"type":"string"}},"additionalProperties":false}}}},"required":["tenant"],"additionalProperties":false},"TenantRelationship":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ITenantRelationship","description":"A relationship to a tenant","type":"object","properties":{"data":{"additionalProperties":false,"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["tenants"]}},"required":["id","type"]},"links":{"$ref":"#/components/schemas/LinksRelated"}},"required":["data","links"],"additionalProperties":false},"LinksRelated":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ILinks","description":"A JSON:API links object with an absolute or relative 'related' link","type":"object","required":["related"],"properties":{"related":{"type":"string"}},"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"Standard JSON:API error response returned when a request fails. Contains an `errors` array with one or more error objects (status, title, and optional detail).","type":"object","required":["errors"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"A single JSON:API error object. `status` is the HTTP status code as a string. `title` is a short, human-readable summary. `detail` provides optional context. `meta` may include structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error (e.g. `/data/attributes/title`).","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"Error stack trace. Only present in non-production environments."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles/{roleId}":{"patch":{"summary":"Update a role","description":"Updates an existing Role by its unique ID. Supports partial updates — only the fields included in the request body are modified. System roles cannot be renamed. The updated role is returned in the response.","operationId":"roleUpdateOne","tags":["Users"],"parameters":[{"name":"roleId","description":"The ID of the role to update","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleUpdateOneRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleUpdateOneResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```