> 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

Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the tenant.

## List users

> Lists the users of your tenant, a page at a time, with the roles each holds \*in that tenant\*. Filter by name, role or status.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"A page of users in a tenant. Each item in `data` is a full user with profile attributes, role relationships, `meta.tenantId` and a self link. The top-level `meta` holds the total count and pagination offsets.","type":"object","additionalProperties":false,"required":["data","meta","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A person with access to Origin Studio, with profile attributes (email, name, picture, status, and the names of the roles held in this tenant) and a relationship to the owning tenant.","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"}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `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":"A user's attributes. For `external` users, the identity provider owns `given_name` and `family_name`, and you can't change them.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL of the user's picture."},"name":{"type":"string","description":"Display name. The server keeps it in sync with `given_name` and `family_name`."},"given_name":{"type":"string","description":"First name. Absent until the user or an administrator sets it; invited accounts start without one."},"family_name":{"type":"string","description":"Last name. Absent until set."},"email":{"type":"string","description":"The user's email address."},"roles":{"type":"array","description":"Role names the user holds *in the requesting tenant*. The same account can hold different roles in other tenants.","items":{"type":"string"}},"source":{"type":"string","description":"Where the user comes from.\n- `local`: created in Origin Studio.\n- `external`: federated from an external identity provider.","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider the user signs in with, such as `local` or `google-oauth2`."},"disabled":{"type":"boolean","description":"Whether the user is deactivated in the requesting tenant only. Unlike `blocked`, you can change it, through `PATCH /users/{userId}`."},"blocked":{"type":"boolean","description":"Whether the whole Auth0 account is blocked, which denies the user in every tenant and every Fabric application. Read-only: someone sets it by hand in Auth0 and this API never changes it, so you can't reactivate a blocked user from the product."},"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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users":{"get":{"summary":"List users","description":"Lists the users of your tenant, a page at a time, with the roles each holds *in that tenant*. Filter by name, role or status.","operationId":"userFindMany","tags":["Users"],"parameters":[{"name":"page.size","description":"Users per page. Defaults to 50.","in":"query","required":false,"schema":{"type":"integer","default":50}},{"name":"page.number","description":"The page to return. Defaults to 0.","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"filter.name","in":"query","required":false,"schema":{"type":"string"},"description":"Matches users by name."},{"name":"filter.roles","in":"query","required":false,"style":"form","explode":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"description":"Matches users by role name. Separate several names with commas."},{"name":"filter.status","in":"query","required":false,"schema":{"type":"string","enum":["active","deactivated"]},"description":"Matches users by status.\n- `active`: every user who isn't deactivated.\n- `deactivated`: disabled in this tenant, or blocked account-wide in Auth0."},{"name":"filter.tenant.id","in":"query","required":false,"schema":{"type":"string"},"description":"Lists the users of this tenant instead of yours. System users only."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUsersResponse"}}}},"400":{"description":"A query parameter is unknown or has an invalid value.","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"}}}}}}}}}
```

## Create users

> Creates one or more users in one request.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"Creates one or more users. Each entry in `data` gives an email address and the role IDs to assign. Each new user gets an invitation email and must verify their account before signing in.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"attributes":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The user's email address."},"roles":{"type":"array","items":{"type":"string"},"description":"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":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","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":"Result of a batch user create. It can partly succeed: check both `data.created` and `data.failed`, even on a 201.","type":"object","properties":{"data":{"type":"object","$ref":"#/components/schemas/CreateUsersData"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"required":["data","jsonapi"],"additionalProperties":false},"CreateUsersData":{"$schema":"http://json-schema.org/draft-07/schema#","title":"ICreateUsersData","description":"Outcome of a batch user create.\n- `created`: users the server created, with their email and assigned role IDs.\n- `failed`: entries it couldn't create, each with the email address, HTTP status code and error details.","type":"object","properties":{"created":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["users"]},"id":{"type":"string"},"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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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":"Creates one or more users in one request.","operationId":"userCreateMany","tags":["Users"],"parameters":[{"name":"tenantId","description":"The tenant to create the users in.","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":"- The body fails validation.\n- A query parameter is unknown or has an invalid value.","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"}}}}}}}}}
```

## Update your own profile

> Updates your own first and last name and keeps the display \`name\` in sync. Answers 403 for users federated from an external identity provider: that provider owns their profile.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":{"ProfileUpdateRequest":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IProfileUpdateRequest","description":"Updates your own name through `PATCH /users/me`. It accepts only the name fields: change `disabled` and role assignments through `PATCH /users/{userId}`. The access token, not the body, decides whose profile the server writes.\n\nThe server normalises whitespace, then checks `maxLength` again. Answers 403 for federated users (`source: external`).","type":"object","required":["data"],"additionalProperties":false,"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"type":"object","required":["id","type","attributes"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Your own user id. Any other id gets 409.","minLength":1},"type":{"type":"string","enum":["users"]},"attributes":{"type":"object","description":"Send at least one field. The server rejects an empty object.","minProperties":1,"additionalProperties":false,"properties":{"given_name":{"type":"string","description":"First name. Must start with a letter. Allows letters of any script, combining marks, and dashes, apostrophes, periods and one or more spaces between letters. The server trims surrounding whitespace and collapses runs of spaces before storing it.","minLength":1,"maxLength":100,"pattern":"^\\u0020*\\p{L}[\\p{L}\\p{M}]*(?:(?:\\.?\\u0020+|[\\p{Pd}\\u0027\\u2019.])[\\p{L}\\p{M}]+)*\\.?\\u0020*$"},"family_name":{"type":"string","description":"Last name, with the same rules as `given_name`. An empty or whitespace-only string clears it.","maxLength":100,"pattern":"^\\u0020*(?:\\p{L}[\\p{L}\\p{M}]*(?:(?:\\.?\\u0020+|[\\p{Pd}\\u0027\\u2019.])[\\p{L}\\p{M}]+)*\\.?)?\\u0020*$"}}}}}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","type":"object","additionalProperties":false,"properties":{"audit":{"type":"object","additionalProperties":false,"properties":{"source":{"type":"string","maxLength":64},"reason":{"type":"string","maxLength":256}}}}},"GetUserResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IGetUserResponse","description":"A single user.","type":"object","additionalProperties":false,"required":["data","meta","links","jsonapi"],"properties":{"data":{"$ref":"#/components/schemas/User"},"meta":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"},"permissions":{"$ref":"#/components/schemas/UserCapabilitiesAttributes"}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A person with access to Origin Studio, with profile attributes (email, name, picture, status, and the names of the roles held in this tenant) and a relationship to the owning tenant.","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"}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `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":"A user's attributes. For `external` users, the identity provider owns `given_name` and `family_name`, and you can't change them.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL of the user's picture."},"name":{"type":"string","description":"Display name. The server keeps it in sync with `given_name` and `family_name`."},"given_name":{"type":"string","description":"First name. Absent until the user or an administrator sets it; invited accounts start without one."},"family_name":{"type":"string","description":"Last name. Absent until set."},"email":{"type":"string","description":"The user's email address."},"roles":{"type":"array","description":"Role names the user holds *in the requesting tenant*. The same account can hold different roles in other tenants.","items":{"type":"string"}},"source":{"type":"string","description":"Where the user comes from.\n- `local`: created in Origin Studio.\n- `external`: federated from an external identity provider.","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider the user signs in with, such as `local` or `google-oauth2`."},"disabled":{"type":"boolean","description":"Whether the user is deactivated in the requesting tenant only. Unlike `blocked`, you can change it, through `PATCH /users/{userId}`."},"blocked":{"type":"boolean","description":"Whether the whole Auth0 account is blocked, which denies the user in every tenant and every Fabric application. Read-only: someone sets it by hand in Auth0 and this API never changes it, so you can't reactivate a blocked user from the product."},"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},"UserCapabilitiesAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserCapabilitiesAttributes","description":"What you can do in the current tenant. The server checks each area live against your roles and policies and reports `canAccess`; a check it can't evaluate reports `false`.","type":"object","additionalProperties":false,"required":["deliveryWorkspace","workingSets","administration","bulkActions"],"properties":{"deliveryWorkspace":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"workingSets":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","additionalProperties":false,"required":["write","delete"],"properties":{"write":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/me":{"patch":{"summary":"Update your own profile","description":"Updates your own first and last name and keeps the display `name` in sync. Answers 403 for users federated from an external identity provider: that provider owns their profile.","operationId":"userProfileUpdateOne","tags":["Users"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateRequest"}}},"required":true},"responses":{"200":{"description":"The updated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"400":{"description":"- The body fails validation or leaves you with no name.\n- The request has a query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: an external identity provider manages your profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found: you have no user record in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"- `data.id` is not your user id.\n- `data.type` is not `users`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: the identity provider rate-limited the update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get your own capabilities

> Returns what you can do in the current tenant: access to administration and the delivery workspace, and whether you can write or delete through bulk actions. Takes no parameters: the server identifies you from the access token.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":{"UserCapabilitiesFindOneResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserCapabilitiesFindOneResponse","description":"Your capabilities in the current tenant, from `/users/me/capabilities`. `GET /users/{userId}` returns the same values in `meta.permissions` when you read your own record.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"properties":{"data":{"type":"object","required":["id","type","attributes","meta"],"additionalProperties":false,"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["userCapabilities"]},"attributes":{"$ref":"#/components/schemas/UserCapabilitiesAttributes"},"meta":{"type":"object","additionalProperties":false,"required":["tenantId"],"properties":{"tenantId":{"type":"string"}}}}},"links":{"type":"object","additionalProperties":false,"required":["self"],"properties":{"self":{"type":"string"}}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"UserCapabilitiesAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserCapabilitiesAttributes","description":"What you can do in the current tenant. The server checks each area live against your roles and policies and reports `canAccess`; a check it can't evaluate reports `false`.","type":"object","additionalProperties":false,"required":["deliveryWorkspace","workingSets","administration","bulkActions"],"properties":{"deliveryWorkspace":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"workingSets":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","additionalProperties":false,"required":["write","delete"],"properties":{"write":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/users/me/capabilities":{"get":{"summary":"Get your own capabilities","description":"Returns what you can do in the current tenant: access to administration and the delivery workspace, and whether you can write or delete through bulk actions. Takes no parameters: the server identifies you from the access token.","operationId":"userCapabilitiesFindOne","tags":["Users"],"responses":{"200":{"description":"Your capabilities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCapabilitiesFindOneResponse"}}}},"400":{"description":"This operation accepts no query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: you have no role in this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a user by ID

> Returns a user's profile and role assignments. The user must belong to your tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"A single user.","type":"object","additionalProperties":false,"required":["data","meta","links","jsonapi"],"properties":{"data":{"$ref":"#/components/schemas/User"},"meta":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"},"permissions":{"$ref":"#/components/schemas/UserCapabilitiesAttributes"}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A person with access to Origin Studio, with profile attributes (email, name, picture, status, and the names of the roles held in this tenant) and a relationship to the owning tenant.","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"}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"BaseResource":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResource","description":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `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":"A user's attributes. For `external` users, the identity provider owns `given_name` and `family_name`, and you can't change them.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL of the user's picture."},"name":{"type":"string","description":"Display name. The server keeps it in sync with `given_name` and `family_name`."},"given_name":{"type":"string","description":"First name. Absent until the user or an administrator sets it; invited accounts start without one."},"family_name":{"type":"string","description":"Last name. Absent until set."},"email":{"type":"string","description":"The user's email address."},"roles":{"type":"array","description":"Role names the user holds *in the requesting tenant*. The same account can hold different roles in other tenants.","items":{"type":"string"}},"source":{"type":"string","description":"Where the user comes from.\n- `local`: created in Origin Studio.\n- `external`: federated from an external identity provider.","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider the user signs in with, such as `local` or `google-oauth2`."},"disabled":{"type":"boolean","description":"Whether the user is deactivated in the requesting tenant only. Unlike `blocked`, you can change it, through `PATCH /users/{userId}`."},"blocked":{"type":"boolean","description":"Whether the whole Auth0 account is blocked, which denies the user in every tenant and every Fabric application. Read-only: someone sets it by hand in Auth0 and this API never changes it, so you can't reactivate a blocked user from the product."},"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},"UserCapabilitiesAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserCapabilitiesAttributes","description":"What you can do in the current tenant. The server checks each area live against your roles and policies and reports `canAccess`; a check it can't evaluate reports `false`.","type":"object","additionalProperties":false,"required":["deliveryWorkspace","workingSets","administration","bulkActions"],"properties":{"deliveryWorkspace":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"workingSets":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","additionalProperties":false,"required":["write","delete"],"properties":{"write":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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 user's profile and role assignments. The user must belong to your tenant.","operationId":"userFindOne","tags":["Users"],"parameters":[{"name":"userId","description":"The user to get.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserResponse"}}}},"400":{"description":"This operation accepts no query parameters.","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"}}}}}}}}}
```

## Delete a user

> Removes the user from your tenant. It does not delete their account.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":{"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false}}},"paths":{"/users/{userId}":{"delete":{"summary":"Delete a user","description":"Removes the user from your tenant. It does not delete their account.","operationId":"userDeleteOne","tags":["Users"],"parameters":[{"name":"userId","description":"The user to delete.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The user is no longer in your tenant. A user who was never in it gets 204 too."},"400":{"description":"- You can't remove yourself.\n- The request has a query parameter.","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"}}}}}}}}}
```

## Update a user

> Updates a user's \`disabled\` status in this tenant, their role assignments, or both. Changes only the fields you send, and returns the updated user.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"Updates a user's `disabled` status in `attributes`, replaces their role assignments in `relationships.roles`, or both. Both apply to the requesting tenant only. `data.id` must match the `userId` path parameter.\n\n`relationships.roles.data` needs at least one role, so unlike the usual JSON:API rule, an empty array can't clear a user's roles. Omit `relationships` to keep roles unchanged, and set `attributes.disabled` to revoke access.","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":{"disabled":{"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":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","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":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `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":"A single user.","type":"object","additionalProperties":false,"required":["data","meta","links","jsonapi"],"properties":{"data":{"$ref":"#/components/schemas/User"},"meta":{"type":"object","required":["tenantId"],"properties":{"tenantId":{"type":"string"},"permissions":{"$ref":"#/components/schemas/UserCapabilitiesAttributes"}},"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"}},"additionalProperties":false},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"User":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUser","description":"A person with access to Origin Studio, with profile attributes (email, name, picture, status, and the names of the roles held in this tenant) and a relationship to the owning tenant.","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"}}}},"required":["type","attributes","relationships"],"additionalProperties":false}]},"UserAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserAttributes","description":"A user's attributes. For `external` users, the identity provider owns `given_name` and `family_name`, and you can't change them.","type":"object","additionalProperties":false,"properties":{"email_verified":{"type":"boolean"},"picture":{"type":"string","description":"URL of the user's picture."},"name":{"type":"string","description":"Display name. The server keeps it in sync with `given_name` and `family_name`."},"given_name":{"type":"string","description":"First name. Absent until the user or an administrator sets it; invited accounts start without one."},"family_name":{"type":"string","description":"Last name. Absent until set."},"email":{"type":"string","description":"The user's email address."},"roles":{"type":"array","description":"Role names the user holds *in the requesting tenant*. The same account can hold different roles in other tenants.","items":{"type":"string"}},"source":{"type":"string","description":"Where the user comes from.\n- `local`: created in Origin Studio.\n- `external`: federated from an external identity provider.","enum":["local","external"]},"identity_provider":{"type":"string","description":"The identity provider the user signs in with, such as `local` or `google-oauth2`."},"disabled":{"type":"boolean","description":"Whether the user is deactivated in the requesting tenant only. Unlike `blocked`, you can change it, through `PATCH /users/{userId}`."},"blocked":{"type":"boolean","description":"Whether the whole Auth0 account is blocked, which denies the user in every tenant and every Fabric application. Read-only: someone sets it by hand in Auth0 and this API never changes it, so you can't reactivate a blocked user from the product."},"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},"UserCapabilitiesAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IUserCapabilitiesAttributes","description":"What you can do in the current tenant. The server checks each area live against your roles and policies and reports `canAccess`; a check it can't evaluate reports `false`.","type":"object","additionalProperties":false,"required":["deliveryWorkspace","workingSets","administration","bulkActions"],"properties":{"deliveryWorkspace":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"workingSets":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"administration":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"bulkActions":{"type":"object","additionalProperties":false,"required":["write","delete"],"properties":{"write":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}},"delete":{"type":"object","additionalProperties":false,"required":["canAccess"],"properties":{"canAccess":{"type":"boolean"}}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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 a user's `disabled` status in this tenant, their role assignments, or both. Changes only the fields you send, and returns the updated user.","operationId":"userUpdateOne","tags":["Users"],"parameters":[{"name":"userId","description":"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":"- The body fails validation.\n- The update changes your own `disabled` flag or removes your own Admin role.\n- The request has a query parameter.","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"}}}},"409":{"description":"- `data.id` names a different user than the URL.\n- `data.type` is not `users`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a user's roles

> Lists the roles assigned to a user. You can always read your own roles. To read another user's, you need permission to read that user, and the user must belong to your tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"All roles in a tenant. Each item in `data` is a full role with its name, description, `dataSource`, timestamps, and tenant and author relationships. Each item's `meta.tenantId` names the owning tenant.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","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 role.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display name, such as `Admin` or `Editor`."},"description":{"type":"string","description":"What the role is for."},"dataSource":{"type":"string","description":"Who owns the role.\n- `fabric`: a system role Fabric provisions. You can't delete it.\n- `custom`: a role the tenant created.","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":"Relationships of a role: the owning `tenant`, and optionally the `author` who created it, with their display name and tenant 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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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":"Lists the roles assigned to a user. You can always read your own roles. To read another user's, you need permission to read that user, and the user must belong to your tenant.","operationId":"userRolesFindMany","tags":["Users"],"parameters":[{"name":"userId","description":"The user, or `me` for yourself.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindManyResponse"}}}},"400":{"description":"This operation accepts no query parameters.","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's effective permissions

> Summarises in plain terms what a user can do across all their roles. The server builds it from the fixed system-role baseline plus the custom policies assigned to those roles; it doesn't evaluate authorization live. You can always read your own permissions. To read another user's, you need permission to read that user, and the user must belong to your tenant.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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, from `/users/{userId}/permissions`) or for one role (from `/roles/{roleId}/permissions`). Both endpoints return this shape.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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"}}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"EffectivePermissionsAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsAttributes","description":"Plain-terms summary of what a role, or the union of a user's roles, can 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 has unrestricted access within `scope`. `resourceGroups` is then empty."},"scope":{"type":"string","enum":["global","tenant"],"description":"How broad the unrestricted access is. Present when `fullAccess` is `true`. `tenant` covers your own tenant."},"baselineScope":{"type":"string","enum":["full","edit","read"],"description":"How broad the system-role baseline alone is, ignoring any custom policy also held. Absent when every role is custom.\n- `full`: an administrator role.\n- `edit`: Editor.\n- `read`: Viewer."},"forbids":{"type":"array","items":{"type":"string"},"description":"Stable keys that name notable restrictions, such as 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 one resource category.","type":"object","additionalProperties":false,"required":["resourceType","grants"],"properties":{"resourceType":{"type":"string","enum":["record","contributor","credits","alternateRunningOrders","media","delivery","dataset","field","recordLayout","recordLifecycle","tenant","user","globalMetadata","bulkActions","workingSet"]},"grants":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveActionGrant"}}}},"EffectiveActionGrant":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveActionGrant","description":"One allowed action on a resource, with where the grant comes from.","type":"object","additionalProperties":false,"required":["verb","source"],"properties":{"verb":{"type":"string","enum":["Create","Read","Update","Delete","Write"],"description":"The allowed action."},"source":{"type":"string","enum":["baseline","policy"],"description":"Where the grant comes from.\n- `baseline`: the role itself, through its system policies.\n- `policy`: a custom policy assigned to the role."},"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":"Conditions that scope a policy-granted action, matching the policy template's conditions. Present only 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":"Allowed lifecycle status ids, keyed by work type (the template's `workTypeLifecycleAccess`). Status ids are unique only 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"}},"recordHistoryAccess":{"type":"boolean","description":"Present and `true` when the granting template also lets the holder read the audit history of the records it scopes."},"recordMoveAccess":{"type":"boolean","description":"Present and `true` when the granting template also lets the holder move the records it scopes under another parent."},"securityTagId":{"type":"string"},"dataGroups":{"type":"object","description":"Allowed entity collections, keyed by work type (the template's `workTypeEntityAccess`).","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"creditsAccess":{"type":"boolean"},"mediaAccess":{"type":"array","items":{"type":"string"}},"externalDataAccess":{"type":"boolean"},"alternateRunningOrdersAccess":{"type":"boolean"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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":"Summarises in plain terms what a user can do across all their roles. The server builds it from the fixed system-role baseline plus the custom policies assigned to those roles; it doesn't evaluate authorization live. You can always read your own permissions. To read another user's, you need permission to read that user, and the user must belong to your tenant.","operationId":"userPermissionsFindOne","tags":["Users"],"parameters":[{"name":"userId","description":"The user, or `me` for yourself.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectivePermissionsResponse"}}}},"400":{"description":"This operation accepts no query parameters.","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"}}}}}}}}}
```

## List roles

> Lists every role in your tenant: the system roles (Admin, Editor, Viewer) and any custom roles.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"All roles in a tenant. Each item in `data` is a full role with its name, description, `dataSource`, timestamps, and tenant and author relationships. Each item's `meta.tenantId` names the owning tenant.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","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 role.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display name, such as `Admin` or `Editor`."},"description":{"type":"string","description":"What the role is for."},"dataSource":{"type":"string","description":"Who owns the role.\n- `fabric`: a system role Fabric provisions. You can't delete it.\n- `custom`: a role the tenant created.","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":"Relationships of a role: the owning `tenant`, and optionally the `author` who created it, with their display name and tenant 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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}}}},"paths":{"/roles":{"get":{"summary":"List roles","description":"Lists every role in your tenant: the system roles (Admin, Editor, Viewer) and any custom roles.","operationId":"roleFindMany","tags":["Users"],"parameters":[{"name":"filter.name","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"string"},"description":"Matches roles by name."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindManyResponse"}}}},"400":{"description":"A query parameter is unknown or has an invalid value.","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"}}}}}}}}}
```

## Create a role

> Creates a custom role in your tenant. Assign security policies to it to control access. You can't create system roles (Admin, Editor, Viewer) here: every tenant already has them.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"Creates a custom role in a tenant.","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 role name. Must be unique in the tenant."},"description":{"type":"string","description":"What the role is for."}}}},"required":["attributes"]}]}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","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 shape for create requests. `type` must match the target resource type. Omit `id` to let the server generate one.","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":"A single role.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","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 role.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display name, such as `Admin` or `Editor`."},"description":{"type":"string","description":"What the role is for."},"dataSource":{"type":"string","description":"Who owns the role.\n- `fabric`: a system role Fabric provisions. You can't delete it.\n- `custom`: a role the tenant created.","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":"Relationships of a role: the owning `tenant`, and optionally the `author` who created it, with their display name and tenant 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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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 custom role in your tenant. Assign security policies to it to control access. You can't create system roles (Admin, Editor, Viewer) here: every tenant already has them.","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":"- The body fails validation or names a reserved role.\n- The request has a query parameter.","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"}}}},"409":{"description":"- A role with this name exists.\n- `data.type` is not `userRoles`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get a role's effective permissions

> Summarises in plain terms what a role can do, built from the fixed system-role baseline plus the custom policies assigned to the role. Needs permission to read policies.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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, from `/users/{userId}/permissions`) or for one role (from `/roles/{roleId}/permissions`). Both endpoints return this shape.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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"}}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"EffectivePermissionsAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectivePermissionsAttributes","description":"Plain-terms summary of what a role, or the union of a user's roles, can 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 has unrestricted access within `scope`. `resourceGroups` is then empty."},"scope":{"type":"string","enum":["global","tenant"],"description":"How broad the unrestricted access is. Present when `fullAccess` is `true`. `tenant` covers your own tenant."},"baselineScope":{"type":"string","enum":["full","edit","read"],"description":"How broad the system-role baseline alone is, ignoring any custom policy also held. Absent when every role is custom.\n- `full`: an administrator role.\n- `edit`: Editor.\n- `read`: Viewer."},"forbids":{"type":"array","items":{"type":"string"},"description":"Stable keys that name notable restrictions, such as 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 one resource category.","type":"object","additionalProperties":false,"required":["resourceType","grants"],"properties":{"resourceType":{"type":"string","enum":["record","contributor","credits","alternateRunningOrders","media","delivery","dataset","field","recordLayout","recordLifecycle","tenant","user","globalMetadata","bulkActions","workingSet"]},"grants":{"type":"array","items":{"$ref":"#/components/schemas/EffectiveActionGrant"}}}},"EffectiveActionGrant":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IEffectiveActionGrant","description":"One allowed action on a resource, with where the grant comes from.","type":"object","additionalProperties":false,"required":["verb","source"],"properties":{"verb":{"type":"string","enum":["Create","Read","Update","Delete","Write"],"description":"The allowed action."},"source":{"type":"string","enum":["baseline","policy"],"description":"Where the grant comes from.\n- `baseline`: the role itself, through its system policies.\n- `policy`: a custom policy assigned to the role."},"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":"Conditions that scope a policy-granted action, matching the policy template's conditions. Present only 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":"Allowed lifecycle status ids, keyed by work type (the template's `workTypeLifecycleAccess`). Status ids are unique only 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"}},"recordHistoryAccess":{"type":"boolean","description":"Present and `true` when the granting template also lets the holder read the audit history of the records it scopes."},"recordMoveAccess":{"type":"boolean","description":"Present and `true` when the granting template also lets the holder move the records it scopes under another parent."},"securityTagId":{"type":"string"},"dataGroups":{"type":"object","description":"Allowed entity collections, keyed by work type (the template's `workTypeEntityAccess`).","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"creditsAccess":{"type":"boolean"},"mediaAccess":{"type":"array","items":{"type":"string"}},"externalDataAccess":{"type":"boolean"},"alternateRunningOrdersAccess":{"type":"boolean"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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":"Summarises in plain terms what a role can do, built from the fixed system-role baseline plus the custom policies assigned to the role. Needs permission to read policies.","operationId":"rolePermissionsFindOne","tags":["Users"],"parameters":[{"name":"roleId","description":"The role.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectivePermissionsResponse"}}}},"400":{"description":"This operation accepts no query parameters.","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 role

> Returns a role in your tenant, with its name, description and security policies.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"A single role.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","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 role.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display name, such as `Admin` or `Editor`."},"description":{"type":"string","description":"What the role is for."},"dataSource":{"type":"string","description":"Who owns the role.\n- `fabric`: a system role Fabric provisions. You can't delete it.\n- `custom`: a role the tenant created.","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":"Relationships of a role: the owning `tenant`, and optionally the `author` who created it, with their display name and tenant 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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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 role in your tenant, with its name, description and security policies.","operationId":"roleFindOne","tags":["Users"],"parameters":[{"name":"roleId","description":"The role to get.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleFindOneResponse"}}}},"400":{"description":"This operation accepts no query parameters.","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"}}}}}}}}}
```

## Delete a role

> Permanently deletes a custom role. You can't delete system roles (Admin, Editor, Viewer). Answers 409 while a user holds the role, a policy or an API key links to it, or the tenant uses it as its default role.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"An optional body with only audit metadata, for mutations that take no other body, such as deletes. Use it to send `meta.audit.source` and `meta.audit.reason`.","type":"object","additionalProperties":false,"properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"}}},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","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":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"conflictItems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"unauthorizedItems":{"type":"array","items":{"type":"string"}}}}}},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false}}},"paths":{"/roles/{roleId}":{"delete":{"summary":"Delete a role","description":"Permanently deletes a custom role. You can't delete system roles (Admin, Editor, Viewer). Answers 409 while a user holds the role, a policy or an API key links to it, or the tenant uses it as its default role.","operationId":"roleDeleteOne","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteMetaOnlyRequest"}}}},"tags":["Users"],"parameters":[{"name":"roleId","description":"The role to delete.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"},"400":{"description":"- The body fails validation.\n- The request has a query parameter.","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"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a role

> Updates a role's \`description\`, the only field you can change, and returns the updated role.

```json
{"openapi":"3.0.3","info":{"title":"Fabric API - Audit","version":"0.9.2817"},"tags":[{"name":"Users","description":"Manage the users and roles of a tenant. A user usually represents a person. A role is a set of security policies that decides what a user can do in the 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":"Updates a role's description. You can't rename a role. Set `data.type` to `userRoles` and `data.id` to the role in the URL.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/WriteRequestMeta"},"data":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"additionalProperties":false,"properties":{"attributes":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","description":"What the role is for."}}}},"required":["attributes"]}]}},"required":["data"],"additionalProperties":false},"WriteRequestMeta":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IWriteRequestMeta","description":"Audit metadata for a write request. `audit.source` names the surface that sent it, such as `studio-web`, `studio-mcp`, `api` or `system`; `audit.reason` is a free-text justification.","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":"A resource identifier. Every resource object carries a unique `id` and a `type`, the resource type name such as `records` or `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 updated role.","type":"object","additionalProperties":false,"required":["data","links","jsonapi"],"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},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"BaseResourceAttributes":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IBaseResourceAttributes","description":"Timestamps on every resource's attributes, as ISO 8601 date-times. `created` marks the resource's creation; `updated` marks its last change.","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 role.","type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display name, such as `Admin` or `Editor`."},"description":{"type":"string","description":"What the role is for."},"dataSource":{"type":"string","description":"Who owns the role.\n- `fabric`: a system role Fabric provisions. You can't delete it.\n- `custom`: a role the tenant created.","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":"Relationships of a role: the owning `tenant`, and optionally the `author` who created it, with their display name and tenant 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},"JsonApiVersion":{"type":"object","description":"The JSON:API version this document conforms to.","properties":{"version":{"type":"string"}},"required":["version"],"additionalProperties":false},"ErrorResponse":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IErrorResponse","description":"The body of a failed request: an `errors` array with one or more error objects.","type":"object","required":["errors","jsonapi"],"additionalProperties":false,"properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}}},"Error":{"$schema":"http://json-schema.org/draft-07/schema#","title":"IError","description":"One JSON:API error object. `status` is the HTTP status code as a string, `title` a short summary and `detail` optional context. `meta` can carry structured conflict or authorization details.","type":"object","additionalProperties":false,"required":["status","title"],"properties":{"status":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","description":"A stable code for the problem that you can act on, when the operation documents one."},"detail":{"type":"string"},"source":{"type":"object","description":"A JSON Pointer to the request field that caused the error, such as `/data/attributes/title`.","properties":{"pointer":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true,"properties":{"stack":{"type":"string","description":"The error's stack trace. Non-production environments only."},"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 a role's `description`, the only field you can change, and returns the updated role.","operationId":"roleUpdateOne","tags":["Users"],"parameters":[{"name":"roleId","description":"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":"- The body fails validation.\n- The request has a query parameter.","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"}}}},"409":{"description":"- `data.id` names a different role than the URL.\n- `data.type` is not `userRoles`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
