openapi: 3.0.1 info: title: Permission Service description: The Permission Service provides APIs for CRUD'ing permissions'. version: '2.0' tags: - name: PermissionService security: - Authorization: [] paths: /users/permissiongroups: get: summary: |- Returns a list of unique values used in permission groups for a particular tenant/scope/domain Permission Level: Read operationId: PermissionService_GetUniquePermissionGroups responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2GetUniquePermissionGroupsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: tenantId description: 'tenant of the permission groups to list, Required: false' in: query required: false schema: type: string - name: domain description: 'domain of the permissions, Required: false' in: query required: false schema: type: string - name: scope description: 'scope of the permissions, Required: false' in: query required: false schema: type: string tags: - PermissionService /users/permissions: get: summary: |- Returns a list of permissions Permission Level: Read operationId: PermissionService_ListPermissions responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ListPermissionsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: tenantId description: 'Tenant of the permissions to list, Required: false' in: query required: false explode: true schema: type: array items: type: string - name: domain description: 'Domain of the permissions, Required: false' in: query required: false schema: type: string - name: scope description: 'Scope of the permissions, Required: false' in: query required: false schema: type: string - name: role.tenantId description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' in: query required: false schema: type: string - name: role.domain description: |- The platform domain. Required: true. (e.g. ZPA, Reflexis, WFC) Defaults to the domain in the request. in: query required: false schema: type: string - name: role.scope description: 'Some more general scoping for the data (like a particular app in the domain). Required: false.' in: query required: false schema: type: string - name: role.roleId description: 'The role ID. Required: true.' in: query required: false schema: type: string - name: role.userIds description: 'The User Ids for the Unique Role Proto, Required: false' in: query required: false explode: true schema: type: array items: type: string - name: user.tenantId description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' in: query required: false schema: type: string - name: user.userId description: 'The user ID. Required: true.' in: query required: false schema: type: string - name: user.firstName description: 'The first name. Required: false.' in: query required: false schema: type: string - name: user.lastName description: 'The last name. Required: false.' in: query required: false schema: type: string - name: pageSize description: |- Requested size of the next page of data. Required: false. If not set, the default page size is 10. in: query required: false schema: type: integer format: int32 - name: pageToken description: |- Token identifying which result to start with, which is returned by a previous list call. Required: false in: query required: false schema: type: string - name: groupId description: Optional - if provided retrieves permissions that are part of the group id passed. in: query required: false schema: type: string - name: sortField description: 'Field to sort by, Default: permissionId, Required: false' in: query required: false schema: type: string - name: sortType description: 'Sort Type for the results, Default: ASC, Required: false' in: query required: false schema: type: string enum: - NONE - ASC - DESC default: NONE - name: type description: 'Type of Permission (example: user, phoenixAuth, permission, *), Required: false' in: query required: false schema: type: string - name: grants description: 'Grants to Permission (example: admin, r, rw, *), Required: false' in: query required: false schema: type: string - name: excludeTenantIds description: 'List of tenant IDs to exclude. Required: false' in: query required: false explode: true schema: type: array items: type: string tags: - PermissionService post: summary: |- Bulk create that creates all the permissions and return a list of errors. Permission Level: Read-Write operationId: PermissionService_CreatePermissions responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2PermissionsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2CreatePermissionsRequest' required: true tags: - PermissionService /users/permissions/map-claims-to-permissions: post: summary: Returns a list of permissions based on the provided list of claims operationId: PermissionService_MapClaimsToPermissions responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2MapClaimsToPermissionsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' requestBody: content: application/json: schema: $ref: '#/components/schemas/v2MapClaimsToPermissionsRequest' required: true tags: - PermissionService /users/permissions/templates:download: get: summary: |- Returns all permissions of a tenant in a CSV format. The CSV file will have the following columns: permission_id,friendly_id,domain,scope,resource_type,grants,description description: 'Permission Level: Read' operationId: PermissionService_GetTemplatedPermissionsFile responses: '200': description: A successful response.(streaming responses) content: application/json: schema: type: object properties: result: $ref: '#/components/schemas/v2GetTemplatedPermissionsFileResponse' error: $ref: '#/components/schemas/googleRpcStatus' title: Stream result of v2GetTemplatedPermissionsFileResponse default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: tenantId description: 'tenant_id of the permissions, Required: false' in: query required: false schema: type: string tags: - PermissionService /users/permissions/tenants: get: summary: Returns a list of ownerTenantIds based on the permission resource type operationId: PermissionService_GetTenantsByResourceType responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2GetTenantsByResourceTypeResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: resourceType description: 'The resource type. Required: true' in: query required: false schema: type: string tags: - PermissionService /users/permissions/{identifier}: get: summary: |- Returns one permission by permission_id and tenant_id Permission Level: Read operationId: PermissionService_GetPermission responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2PermissionResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: identifier description: The identifier value used to retrieve the Permission in: path required: true schema: type: string - name: ownerTenantId description: 'The tenant of the permission, Required: false' in: query required: false schema: type: string - name: identifierType description: |- The identifier type - PERMISSION_ID: By Permission ID. This is the default option. - FRIENDLY_ID: By friendly ID. in: query required: false schema: type: string enum: - PERMISSION_ID - FRIENDLY_ID default: PERMISSION_ID tags: - PermissionService delete: summary: |- Deletes a permission. permission_id and tenant is required. Permission Level: Read-Write operationId: PermissionService_DeletePermission responses: '200': description: A successful response. content: application/json: schema: type: object properties: {} default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: identifier description: The identifier value used to delete the Permission in: path required: true schema: type: string - name: ownerTenantId description: 'The tenant of the permission, Required: false' in: query required: false schema: type: string - name: identifierType description: |- The identifier type - PERMISSION_ID: By Permission ID. This is the default option. - FRIENDLY_ID: By friendly ID. in: query required: false schema: type: string enum: - PERMISSION_ID - FRIENDLY_ID default: PERMISSION_ID tags: - PermissionService put: summary: |- Updates a permission. permission_id, tenant and fields to update are required in update_permission Permission Level: Read-Write operationId: PermissionService_UpdatePermission responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2PermissionResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: identifier description: The identifier value used to update the Permission in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PermissionServiceUpdatePermissionBody' required: true tags: - PermissionService /users/permissions/{permissionId}/users: delete: summary: |- Remove users from a Permission. permission_id, tenant and a list of users are required to be removed from permission. This in not a recommended service. Please remove users from a role (see role.proto) to remove user permissions. Permission Level: Read-Write operationId: PermissionService_DeletePermissionUsers responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2PermissionResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: permissionId description: 'permission_id of the permission, Required: true' in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PermissionServiceDeletePermissionUsersBody' required: true tags: - PermissionService post: summary: |- Add users to a Permission. permission_id, tenant and a list of users are required to be added to permission. This in not a recommended service. Please add permissions and users to a role (see CreatePermission above or role.proto) to grant user permissions. Permission Level: Read-Write operationId: PermissionService_AddPermissionUsers responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2PermissionResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: permissionId description: 'permission_id of the permission, Required: true' in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PermissionServiceAddPermissionUsersBody' required: true tags: - PermissionService /users/{userId}/permissions: get: summary: |- Returns a list of permissions of a user in a non-paginated response Permission Level: Read operationId: PermissionService_ListUserPermissions responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v2ListUserPermissionsResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' parameters: - name: userId description: 'The user ID. Required: true.' in: path required: true schema: type: string - name: tenantId description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' in: query required: false schema: type: string - name: roleMode description: |2- - ALL_ROLES: Include all roles - STATIC: Only include permissions from static roles - DYNAMIC: Only include permissions from dynamic roles in: query required: false schema: type: string enum: - ALL_ROLES - STATIC - DYNAMIC default: ALL_ROLES tags: - PermissionService servers: - url: https://prod-ui-zwseuprod01p.pp.zebra.com/api description: EU Server - url: https://prod-ui-zwsusprod01p.pp.zebra.com/api description: NA Server components: schemas: ListUserPermissionsRequestRoleMode: type: string enum: - ALL_ROLES - STATIC - DYNAMIC default: ALL_ROLES description: |- - ALL_ROLES: Include all roles - STATIC: Only include permissions from static roles - DYNAMIC: Only include permissions from dynamic roles title: |- What user roles should be considered to resolve permissions Use case: Upon authentication, only permissions from static roles should be considered Permissions assigned directly to the user are not affected PermissionServiceAddPermissionUsersBody: type: object properties: ownerTenantId: type: string title: 'tenant of the permission, Required: false' users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: 'list of users (user_ids) to add to the permission, Required: true' PermissionServiceDeletePermissionUsersBody: type: object properties: ownerTenantId: type: string title: 'tenant of the permission, Required: false' users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: 'list of users (user_ids) to remove from the permission, Required: true' PermissionServiceUpdatePermissionBody: type: object properties: ownerTenantId: type: string title: 'The tenant of the permission, Required: false' identifierType: $ref: '#/components/schemas/v2PermissionIdentifierType' updatePermission: $ref: '#/components/schemas/v2UpdatePermissionProto' updateFieldMask: type: string title: |- FieldMask to control what fields are to be updated, Required: false Valid path names ("scope","description","grants","tenants","targets","users","group_ids","type") as related to UpdatePermissionProto commonsSortType: type: string enum: - NONE - ASC - DESC default: NONE protobufAny: type: object properties: '@type': type: string additionalProperties: {} rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' v2CreatePermissionProto: type: object properties: friendlyId: type: string title: 'A unique identifier of a permission in a tenant, Required: false' domain: type: string title: 'The platform domain (example: zpa, reflexis, wfc), Required: true' scope: type: string title: 'Some more general scoping for the data (like a particular app in the domain), Required: false' description: type: string title: 'Permission Description, Required: false' type: type: string title: 'Type of Permission (example: user, phoenixAuth, permission, *), Required: true' grants: type: string title: |- Grants to Permission (example: admin, r, rw, *, or a combination of all of these in a comma separated list) see https://confluence.zebra.com/pages/viewpage.action?pageId=118425283, Required: true tenants: type: string title: 'Tenants to which permission belongs to. (example: *, ^ or comma-separated list of tenants), Default: owner_tenant_id, Required: false' targets: type: array items: $ref: '#/components/schemas/v2TargetProto' title: 'targets for permission, Required: false' roles: type: array items: $ref: '#/components/schemas/v2UniqueRoleProto' title: 'List of roles to add to this permission, Required: either of users/roles is required' users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: 'List of users to add to this permission, Required: either of users/roles is required' systemLevel: type: boolean description: |- whether permission is a system_level permission or not, Default: false, Required: false Note: If permission is being created by a user from tenant other than "root" then system_level will be set to false irrespective of what value is set for this boolean. groupIds: type: array items: type: string title: String for grouping permissions typeFriendlyName: type: string description: 'Friendly name of the type of permission. Required: false.' grantFriendlyName: type: string description: 'Friendly name of the grant from PERMISSION_GRANTS property. Required: false.' grantDescription: type: string description: 'Description of the grant from PERMISSION_GRANTS property. Required: false.' title: Protobuf model to create a permission v2CreatePermissionsRequest: type: object properties: ownerTenantId: type: string title: 'tenant of the permission, Required: false' permissions: type: array items: $ref: '#/components/schemas/v2CreatePermissionProto' title: 'list of permissions to upload, Required: true' rollback: type: boolean title: 'Whether to rollback entire transaction if error in any permissions, Default: false, Required: false' v2GetTemplatedPermissionsFileResponse: type: object properties: data: type: string format: byte title: Array of bytes representing csv file data of templated permissions v2GetTenantsByResourceTypeResponse: type: object properties: tenants: type: array items: type: string title: List of owner_tenant_ids of the permissions v2GetUniquePermissionGroupsResponse: type: object properties: groupIds: type: array items: type: string v2ListPermissionsResponse: type: object properties: permissions: type: array items: $ref: '#/components/schemas/v2PermissionResponse' nextPageToken: type: string description: Token that can be passed to `ListPermissionsRequest` to resume a paginated query. v2ListUserPermissionsResponse: type: object properties: permissions: type: array items: $ref: '#/components/schemas/v2PermissionResponse' v2MapClaimsToPermissionsRequest: type: object properties: tenantId: type: string title: 'The tenant ID. Required: false' userId: type: string title: 'The user ID. Required: false' claims: type: object additionalProperties: type: string title: IDPC claims to map to permissions v2MapClaimsToPermissionsResponse: type: object properties: permissions: type: array items: $ref: '#/components/schemas/v2PermissionResponse' title: List of permissions obtained from IDP claims, if any v2PermissionIdentifierType: type: string enum: - PERMISSION_ID - FRIENDLY_ID default: PERMISSION_ID description: |- - PERMISSION_ID: By Permission ID. This is the default option. - FRIENDLY_ID: By friendly ID. title: Specifies the types of permission identifiers available to retrieve/update/delete a Permission v2PermissionResponse: type: object properties: permissionId: type: string title: Generated at the time of creation (Randomly generated String) ownerTenantId: type: string description: Owner tenant of the permission to which it belongs. friendlyId: type: string title: 'A unique identifier of a permission in a tenant, Required: false' domain: type: string title: 'The platform domain (example: zpa, reflexis, wfc)' scope: type: string title: Some more general scoping for the data (like a particular app in the domain) description: type: string title: Permission Description type: type: string title: 'Type of Permission (example: user, phoenixAuth, permission, *)' grants: type: string title: 'Grants to Permission (example: admin, r, rw, *)' tenants: type: string title: 'Tenants to which permission belongs to. (example: *, ^ or comma-separated list of tenants)' targets: type: array items: $ref: '#/components/schemas/v2TargetProto' title: targets for permission roles: type: array items: $ref: '#/components/schemas/v2UniqueRoleProto' title: List of roles that have this permission users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: List of users that have this permission systemLevel: type: boolean title: |- Used to specify whether permission is a system_level permission or not. A system level permission cannot be deleted. System level means something Phoenix needs to function and only should be created by services or trained Zebra employee's groupIds: type: array items: type: string title: Permission group IDs deactivated: type: boolean title: 'Option to control if the permission is deactivated, Required: false' creationTime: type: string format: date-time title: Time of creation of permission entity lastUpdated: type: string format: date-time title: Time of most recent update to the permission entity typeFriendlyName: type: string description: Friendly name of the type of permission. Blank if not set. scopeFriendlyName: type: string description: Friendly name of the scope of the permission. Blank if not set. grantFriendlyName: type: string description: Friendly name of the grant from PERMISSION_GRANTS property. Blank if not set. grantDescription: type: string description: Description of the grant from PERMISSION_GRANTS property. Blank if not set. title: Main Permission data model v2PermissionsResponse: type: object properties: permissions: type: array items: $ref: '#/components/schemas/v2PermissionResponse' title: list of users for the given tenant v2TargetProto: type: object properties: idType: type: string title: The ID type of what the target applies to. Typically in the form by{{Thing}} id: type: string description: The value that the target applies to. description: |- Targets describe what the permission applies to. For example if you wanted to have an admin permission and wanted the user to only have permissions on unitA and unitB you would design your target like this: id_type = "byUnit" id = "unitA,unitB" The actual values used are free form and determined by the application when designing their authorization model. Some standards we try to stick to despite the free form are: id_type we try and model with by{{Thing}}. The most common use case for this is byTenant (which we moved up to the base permission level, see permission.proto). For ID, which is the actual value this is giving access to we recommend using: * - if the user should have access to everything in that Thing. so a byTenant - * permission would give access to ALL tenants. ^ - gives access to the user's own Thing. For example - byTenant - ^ would give access to the user's own tenant. This gives the ability to create a single permission that can be used by multiple roles. Otherwise we use a specific value, so byTenant - mytenant would give access to the "mytenant" tenant. This is best used for giving access to someone outside of our tenant to your tenant, or if you have a list of specific things that wont change depending on who has access to the permission. v2UniqueRoleProto: type: object properties: tenantId: type: string description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' domain: type: string description: |- The platform domain. Required: true. (e.g. ZPA, Reflexis, WFC) Defaults to the domain in the request. scope: type: string description: 'Some more general scoping for the data (like a particular app in the domain). Required: false.' roleId: type: string description: 'The role ID. Required: true.' userIds: type: array items: type: string title: 'The User Ids for the Unique Role Proto, Required: false' v2UniqueUserProto: type: object properties: tenantId: type: string description: 'The ID of the tenant. Required: false. Defaults to the tenant of the user making the call.' userId: type: string description: 'The user ID. Required: true.' firstName: type: string description: 'The first name. Required: false.' lastName: type: string description: 'The last name. Required: false.' v2UpdateDeactivated: type: object properties: deactivated: type: boolean v2UpdatePermissionProto: type: object properties: scope: type: string title: 'Updated general scoping for permission, Required: false' description: type: string title: 'Updated permission description, Required: false' type: type: string title: 'Update type of Permission (example: user, phoenixAuth, permission, *), Required: false' grants: type: string title: |- Updated grants to Permission (example: admin, r, rw, * or a combination of all of these in a comma separated list), see https://confluence.zebra.com/pages/viewpage.action?pageId=118425283. If specified the grant must be enabled, Required: false tenants: type: string title: 'Updated tenants to which permission belongs to. (example: *, ^ or comma-separated list of tenants), Required: false' targets: type: array items: $ref: '#/components/schemas/v2TargetProto' title: 'Updated targets for permission, Required: false' roles: type: array items: $ref: '#/components/schemas/v2UniqueRoleProto' title: 'Update list of roles for permission, Required: false' users: type: array items: $ref: '#/components/schemas/v2UniqueUserProto' title: 'Update list of users for permission, Required: false' groupIds: type: array items: type: string title: Add group id to permission friendlyId: type: string title: 'A unique identifier of a permission in a tenant, Required: false' deactivated: $ref: '#/components/schemas/v2UpdateDeactivated' grantFriendlyName: type: string description: 'Friendly name of the grant from PERMISSION_GRANTS property. Required: false.' grantDescription: type: string description: 'Description of the grant from PERMISSION_GRANTS property. Required: false.' title: Protobuf made for permission fields to update (only those fields which needs to be updated should be provided) googleRpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: '#/components/schemas/protobufAny' securitySchemes: Authorization: type: apiKey description: Bearer token name: Authorization in: header