{ "info": { "title": "roles", "version": "" }, "paths": { "/api/v1/roles": { "get": { "tags": [ "roles" ], "summary": "List roles", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRolesResult" } } }, "description": "An array of roles, and pagination links." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Invalid request parameters for querying roles." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Unauthorized, JWT is invalid or not provided." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "headers": { "retry-after": { "schema": { "type": "integer", "default": 1 }, "description": "The amount of seconds to wait before retrying the request." } }, "description": "Request has been rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Internal server error." } }, "parameters": [ { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "The advanced filtering to use for the query. Refer to [RFC 7644](https://datatracker.ietf.org/doc/rfc7644/) for the syntax. All conditional statements within this query parameter are case insensitive." }, { "in": "query", "name": "limit", "schema": { "type": "number", "default": 20, "maximum": 100, "minimum": 1 }, "description": "The number of roles to retrieve." }, { "in": "query", "name": "next", "schema": { "type": "string", "format": "uid", "example": "507f191e810c19729de860ea" }, "description": "The next page cursor." }, { "in": "query", "name": "prev", "schema": { "type": "string", "format": "uid", "example": "507f191e810c19729de86gea" }, "description": "The previous page cursor." }, { "in": "query", "name": "sort", "schema": { "type": "string" }, "description": "Optional resource field name to sort on, eg. name. Can be prefixed with +/- to determine order, defaults to (+) ascending." }, { "in": "query", "name": "totalResults", "schema": { "type": "boolean" }, "description": "Determines wether to return a count of the total records matched in the query. Defaults to false." } ], "description": "Returns a list of roles using cursor-based pagination.", "operationId": "getRoles", "x-qlik-visibility": "public", "x-qlik-stability": "stable", "x-qlik-deprecated": false, "x-qlik-tier": { "tier": "1", "limit": 1000 } }, "post": { "tags": [ "roles" ], "summary": "Create role", "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Invalid request was made." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Unauthorized to create role." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Forbidden from creating role." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "headers": { "retry-after": { "schema": { "type": "integer", "default": 1 }, "description": "The amount of seconds to wait before retrying the request." } }, "description": "Request has been rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Internal server error." } }, "description": "Creates a custom role. Role names must be unique, and there is a maximum of 500 custom roles per tenant. Requestor must be assigned the `TenantAdmin` role.", "operationId": "createRole", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRole" } } }, "required": true }, "x-qlik-visibility": "public", "x-qlik-stability": "stable", "x-qlik-deprecated": false, "x-qlik-tier": { "tier": "2", "limit": 100 } } }, "/api/v1/roles/{id}": { "get": { "tags": [ "roles" ], "summary": "Get role by ID", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } }, "description": "Request successfully completed." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Role ID not found or Invalid format." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "headers": { "retry-after": { "schema": { "type": "integer", "default": 1 }, "description": "The amount of seconds to wait before retrying the request." } }, "description": "Request has been rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Internal Server Error." } }, "parameters": [ { "in": "path", "name": "id", "schema": { "$ref": "#/components/schemas/Role/properties/id" }, "required": true, "description": "The unique identifier for the role." } ], "description": "Returns the requested role.", "operationId": "getRoleById", "x-qlik-visibility": "public", "x-qlik-stability": "stable", "x-qlik-deprecated": false, "x-qlik-tier": { "tier": "1", "limit": 1000 } }, "patch": { "tags": [ "roles" ], "summary": "Update role by ID", "responses": { "204": { "content": { "application/json": {} }, "description": "Updated" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Invalid request was made." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Unauthorized to update role." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Forbidden from updating role." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Role ID not found or Invalid format." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "headers": { "retry-after": { "schema": { "type": "integer", "default": 1 }, "description": "The amount of seconds to wait before retrying the request." } }, "description": "Request has been rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Internal server error." } }, "parameters": [ { "in": "path", "name": "id", "schema": { "$ref": "#/components/schemas/Role/properties/id" }, "required": true, "description": "The unique identifier for the role." } ], "description": "Updates the requested role. Only applicable to roles of type `custom`. Requestor must be assigned the `TenantAdmin` role.", "operationId": "updateRoleById", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRoles" } } }, "required": true }, "x-qlik-visibility": "public", "x-qlik-stability": "stable", "x-qlik-deprecated": false, "x-qlik-tier": { "tier": "2", "limit": 100 } }, "delete": { "tags": [ "roles" ], "summary": "Delete role by ID", "responses": { "204": { "content": { "application/json": {} }, "description": "Deleted successfully." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Invalid request was made." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Unauthorized to delete role." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Forbidden from deleting role." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "headers": { "retry-after": { "schema": { "type": "integer", "default": 1 }, "description": "The amount of seconds to wait before retrying the request." } }, "description": "Request has been rate limited." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } }, "description": "Internal server error." } }, "parameters": [ { "in": "path", "name": "id", "schema": { "$ref": "#/components/schemas/Role/properties/id" }, "required": true, "description": "The unique identifier for the role." } ], "description": "Deletes the requested role. Role can only be deleted if it has been unassigned from all users and groups. Only applicable to roles of type `custom`. Requestor must be assigned the `TenantAdmin` role.", "operationId": "deleteRoleById", "x-qlik-visibility": "public", "x-qlik-stability": "stable", "x-qlik-deprecated": false, "x-qlik-tier": { "tier": "2", "limit": 100 } } } }, "openapi": "3.0.0", "components": { "schemas": { "CreateRole": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Role name, needs to be unique" }, "description": { "type": "string", "description": "Role description" }, "assignedScopes": { "type": "array", "items": { "type": "string" }, "description": "Selection of scopes to assign to role" } } }, "Error": { "type": "object", "required": [ "code", "title" ], "properties": { "code": { "type": "string", "description": "The error code." }, "meta": { "type": "object", "description": "Additional properties relating to the error." }, "title": { "type": "string", "description": "Summary of the problem." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "source": { "type": "object", "properties": { "pointer": { "type": "string", "description": "A JSON Pointer to the property that caused the error." }, "parameter": { "type": "string", "description": "The URI query parameter that caused the error." } }, "description": "References to the source of the error." } }, "description": "An error object describing the error." }, "Errors": { "type": "object", "example": { "errors": [ { "code": "IDENTITIES-10402", "title": "Not Found" } ], "traceId": "0000000000000000200ba0714061b982" }, "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" }, "description": "An array of errors related to the operation." }, "traceId": { "type": "string", "description": "A unique identifier for tracing the error." } }, "description": "The error response object describing the error from the handling of an HTTP request." }, "Links": { "type": "object", "required": [ "self" ], "properties": { "next": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://mytenant.us.qlikcloud.com/api/v1/roles?next=QaFdFYW6pImZvRgFaDyB1UffNgfs4mRd" } }, "description": "Link to the next page of items" }, "prev": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://mytenant.us.qlikcloud.com/api/v1/roles?prev=QaFdFYW6pImZvRgFaDyB1UffNgfs4mRd" } }, "description": "Link to the previous page of items" }, "self": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://mytenant.us.qlikcloud.com/api/v1/roles" } }, "description": "Link to the current page of items" } }, "description": "Contains pagination links" }, "ListRolesResult": { "type": "object", "required": [ "links", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" }, "description": "An array of roles." }, "links": { "$ref": "#/components/schemas/Links" }, "totalResults": { "type": "integer", "description": "Indicates the total number of matching documents. Will only be returned if the query parameter \"totalResults\" is true." } } }, "PatchRole": { "type": "object", "required": [ "op", "path", "value" ], "properties": { "op": { "enum": [ "replace", "add", "remove-value" ], "type": "string", "example": "replace" }, "path": { "enum": [ "/name", "/description", "/assignedScopes", "/assignedScopes/-" ], "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "description": "A JSON Patch document as defined in http://tools.ietf.org/html/rfc6902." }, "PatchRoles": { "type": "array", "items": { "$ref": "#/components/schemas/PatchRole" }, "example": [ { "op": "replace", "path": "/name", "value": "Role1" }, { "op": "replace", "path": "/assignedScopes", "value": [ "knowledgebase" ] }, { "op": "add", "path": "/assignedScopes/-", "value": "knowledgebase" }, { "op": "remove-value", "path": "/assignedScopes", "value": "knowledgebase" }, { "op": "replace", "path": "/description", "value": "My custom role description" } ], "description": "An array of JSON Patch documents" }, "Role": { "type": "object", "required": [ "id", "tenantId", "name", "type", "description", "createdAt", "lastUpdatedAt", "links" ], "properties": { "id": { "type": "string", "format": "uid", "example": "507f191e810c19729de860ea", "readOnly": true, "description": "The unique identifier for the role.", "x-qlik-filterable": true }, "name": { "type": "string", "example": "My Custom Role", "description": "The name of the role.", "x-qlik-filterable": true }, "type": { "enum": [ "default", "custom" ], "type": "string", "example": "custom", "description": "The type of role.", "x-qlik-filterable": true }, "level": { "enum": [ "admin", "user" ], "type": "string", "example": "user", "description": "The level of access associated to the role.", "x-qlik-filterable": true }, "links": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "object", "required": [ "href" ], "properties": { "href": { "type": "string", "format": "uri", "example": "http://mytenant.us.qlikcloud.com/api/v1/roles/507f191e810c19729de860ea", "description": "Link to the role." } } } }, "description": "Contains links for the role." }, "canEdit": { "type": "boolean", "default": false, "readOnly": true, "description": "Indicate if role can be edited by tenant (Shown as Profile in MC)" }, "fullUser": { "type": "boolean", "readOnly": true, "description": "DEPRECATED. Use userEntitlementType instead for impact of roles on user entitlements with a capacity-based subscription.", "x-qlik-deprecated": true }, "tenantId": { "type": "string", "format": "uid", "example": "q3VRZ4YMixRaLKEPhkZWM-XMIDN7cO8f", "description": "The tenant unique identifier associated with the given Role.", "x-qlik-filterable": true }, "canDelete": { "type": "boolean", "default": false, "readOnly": true, "description": "Indicate if role can be deleted" }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-03-21T17:32:28Z", "description": "The timestamp for when the role was created.", "x-qlik-filterable": true }, "createdBy": { "type": "string", "readOnly": true, "description": "Id of user that created role" }, "updatedBy": { "type": "string", "readOnly": true, "description": "Id of user that last updated this role" }, "description": { "type": "string", "example": "Grants permission to edit resource 'foo'", "description": "Descriptive text for the role.", "x-qlik-filterable": true }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "edit_foo" ], "description": "An array of permissions associated with the role.", "x-qlik-filterable": true }, "lastUpdatedAt": { "type": "string", "format": "date-time", "example": "2021-03-22T10:01:02Z", "description": "The timestamp for when the role was last updated.", "x-qlik-filterable": true }, "assignedScopes": { "type": "array", "items": { "type": "string" }, "description": "Selection of scopes added to this Role" }, "userEntitlementType": { "type": "string", "example": "fullUser", "readOnly": true, "description": "Indicate whether this role will trigger promotion of a user from a basic to a full user on tenants with a capacity-based subscription. Does not apply to tenants with a user-based subscription. Returns fullUser if it will trigger promotion." } } } } }, "servers": [ { "url": "https://{tenant}.{region}.qlikcloud.com", "variables": { "region": { "default": "us", "description": "The region the tenant is hosted in" }, "tenant": { "default": "your-tenant", "description": "Name of the tenant that will be called" } } } ] }