API Reference Resources - HealthCatalyst/Fabric.Authorization GitHub Wiki

Resources

Clients

Operations for managing clients

Registers a new client

POST /v1/clients
Parameters
Type Name Description Schema
Body Client required The client to register ClientApiModel
Responses
HTTP Code Description Schema
201 Created ClientApiModel
400 Client object in body failed validation Error
403 Client does not have access No Content
409 Client with specified id already exists Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write,fabric/authorization.manageclients

Gets all registered clients

GET /v1/clients
Responses
HTTP Code Description Schema
200 OK ClientApiModel
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read,fabric/authorization.manageclients

Gets a single client

GET /v1/clients/{clientid}
Parameters
Type Name Description Schema
Path clientid required ClientId to use for the request integer
Responses
HTTP Code Description Schema
200 Client found ClientApiModel
403 Client does not have access No Content
404 Client with specified id was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read,fabric/authorization.manageclients

Deletes a client

DELETE /v1/clients/{clientid}
Parameters
Type Name Description Schema
Path clientid required ClientId to use for the request integer
Responses
HTTP Code Description Schema
204 Client deleted No Content
403 Client does not have access No Content
404 Client with specified id was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write,fabric/authorization.manageclients

Fabric.Identity Search

Operations for searching Fabric.Identity

Searches for users and groups by client ID and other optional parameters.

GET /v1/members
Parameters
Type Name Description Schema
Query client_id required Client ID string
Query filter optional Text filter string
Query page_number optional Page number integer
Query page_size optional Page size integer
Query sort_direction optional Sort direction string
Query sort_key optional Sort key string
Responses
HTTP Code Description Schema
200 OK < MemberSearchResponse > array
206 Partial success (e.g., results were found in Fabric.Authorization but the call out to Fabric.Identity failed). Properties populated by Fabric.Identity data are FirstName, MiddleName, LastName, and LastLoginDateTimeUtc. < MemberSearchResponse > array
400 Group already exists Error
403 Client does not have the required scopes to read data in Fabric.Authorization (fabric/authorization.read). No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Groups

Operations for managing groups

Adds a new group

POST /v1/groups
Description

GroupSource can be either "Custom" for creating custom groups in Fabric or the displayName of the 3rd party identity provider if the group is from an external Idp. If groupSource is empty, it will be defaulted to the group source defined in the appsettings.json

Parameters
Type Name Description Schema
Body Group required The group to add GroupRoleApiModel
Responses
HTTP Code Description Schema
201 Created GroupRoleApiModel
403 Client does not have access No Content
409 Group already exists Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read,fabric/authorization.write

Gets groups by name and an optional type

GET /v1/groups
Parameters
Type Name Description Schema
Query name required the group name string
Query type optional the type of group, either 'custom' or 'directory' string
Responses
HTTP Code Description Schema
200 OK GroupRoleApiModel
400 No name parameter was provided or an invalid type parameter was provided Error
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Updates a list of groups, useful for syncing 3rd party ID Provider groups with Fabric.Authorization groups.

POST /v1/groups/UpdateGroups
Parameters
Type Name Description Schema
Body Group required The groups to update < GroupRoleApiModel > array
Responses
HTTP Code Description Schema
204 Groups updated No Content
403 Client does not have access No Content
409 Group already exists Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets a group by name

GET /v1/groups/{groupName}
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
200 OK GroupRoleApiModel
403 Client does not have access No Content
404 Group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes a group

DELETE /v1/groups/{groupName}
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
204 Group deleted No Content
403 Client does not have access No Content
404 Group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Updates an existing group

PATCH /v1/groups/{groupName}
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body GroupPatchApiRequest required The model containing the fields to update (currently only DisplayName and Description can be modified) GroupPatchApiRequest
Responses
HTTP Code Description Schema
200 Updated GroupRoleApiModel
403 Client does not have access No Content
404 Group with specified name does not exist Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Adds 1 or more directory groups to a custom group.

POST /v1/groups/{groupName}/groups
Description
  1. Only custom groups can be a parent group. 2) Only directory groups can be child groups.
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body Groups required The directory groups to add < GroupIdentifierApiRequest > array
Responses
HTTP Code Description Schema
200 Created GroupRoleApiModel
400 The specified parent group is a directory group or 1 or more specified child groups is a custom group Error
403 Client does not have write access or user does not have permissions to write to grain and securable items for roles tied to custom group Error
404 Group with specified name was not found or 1 or more of the specified child groups could not be found Error
409 1 or more directory groups is already a child of the specified custom group Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets child groups for a custom group

GET /v1/groups/{groupName}/groups
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
200 OK < GroupRoleApiModel > array
403 Client does not have access Error
404 Custom group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Removes 1 or more directory groups from a custom group.

DELETE /v1/groups/{groupName}/groups
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body Groups required The groups to remove < UserIdentifierApiRequest > array
Responses
HTTP Code Description Schema
200 Removed GroupRoleApiModel
403 Client does not have write access or user does not have permissions to write to grain and securable items for roles tied to custom group Error
404 Group with specified name was not found or 1 or more of the specified child groups could not be found Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Adds a collection of roles to a group

POST /v1/groups/{groupName}/roles
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body Roles required The roles to add < RoleApiModel > array
Responses
HTTP Code Description Schema
200 Roles added to group GroupRoleApiModel
400 List of roles in body failed validation Error
403 Client does not have access or User does not have access to add the specified roles. No Content
404 Group with specified name was not found or the role was not found Error
409 Role with specified name already exists for the group Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets roles for a group by group name and (optionally) identity provider and tenant ID

GET /v1/groups/{groupName}/roles
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
200 OK < RoleApiModel > array
403 Client does not have access No Content
404 Group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes 1 or more roles from a group

DELETE /v1/groups/{groupName}/roles
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body Roles required The roles to delete < RoleIdentifierApiRequest > array
Responses
HTTP Code Description Schema
200 Updated group entity including any mapped roles GroupRoleApiModel
403 Client does not have access Error
404 Group with specified name was not found or the role was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets users for a custom group by group name

GET /v1/groups/{groupName}/users
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
200 OK < UserApiModel > array
403 Client does not have access Error
404 Group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes a user from a group

DELETE /v1/groups/{groupName}/users
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query identityProvider optional The identity provider (IdP) of the group string
Query tenantId optional The identity provider (IdP) of the group string
Body identityProvider required 3rd party identity provider (IdP) of the user string
Body subjectId required Subject ID of the user string
Responses
HTTP Code Description Schema
200 Updated group entity including any mapped users GroupUserApiModel
403 Client does not have access Error
404 Group with specified name was not found or the user was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets roles for a group by group name, grain, and securable item

GET /v1/groups/{groupName}/{grain}/{securableItem}/roles
Parameters
Type Name Description Schema
Path groupName required The name of the group string
Query grain optional grain string
Query identityProvider optional The identity provider (IdP) of the group string
Query securableItem optional securable item string
Query tenantId optional The identity provider (IdP) of the group string
Responses
HTTP Code Description Schema
200 OK < RoleApiModel > array
403 Client does not have access No Content
404 Group with specified name was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Permissions

Operations for managing permissions

Adds a new permissions

POST /v1/permissions
Parameters
Type Name Description Schema
Body Permission required The permission to add PermissionApiModel
Responses
HTTP Code Description Schema
201 Permission was created No Content
400 Permission data in body is invalid Error
403 Client does not have access No Content
409 Permission with the specified id already exists No Content
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Get permissions for a particular grain and securable item

GET /v1/permissions/{grain}/{securableItem}
Parameters
Type Name Description Schema
Path grain required The top level grain to return permissions for string
Path securableItem required The specific securableItem within the grain to return permissions for string
Responses
HTTP Code Description Schema
200 OK < PermissionApiModel > array
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Get permissions for a particular grain, securable item, and permission name

GET /v1/permissions/{grain}/{securableItem}/{permissionName}
Parameters
Type Name Description Schema
Path grain required The top level grain to return permissions for string
Path permissionName required The name of the permission string
Path securableItem required The specific securableItem within the grain to return permissions for string
Responses
HTTP Code Description Schema
200 OK < PermissionApiModel > array
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Get a permission by permission id

GET /v1/permissions/{permissionId}
Parameters
Type Name Description Schema
Path permissionId required The id of the permission string
Responses
HTTP Code Description Schema
200 Permission was found PermissionApiModel
400 Permission id must be a Guid Error
403 Client does not have access No Content
404 Permission with the specified id was not found No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes a permission

DELETE /v1/permissions/{permissionId}
Parameters
Type Name Description Schema
Path permissionId required The id of the permission string
Responses
HTTP Code Description Schema
204 Permission with the specified id was deleted No Content
400 Permission id must be a guid Error
403 Client does not have access No Content
404 Permission with specified id was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Roles

Operations for managing roles

Add a new role

POST /v1/roles
Parameters
Type Name Description Schema
Body Role required The role to add RoleApiModel
Responses
HTTP Code Description Schema
201 Created RoleApiModel
400 Role with specified id already exists or Role object in body failed validation Error
403 Client does not have access No Content
409 Role with specified id already exists Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Get roles associated with a securable item

GET /v1/roles/{grain}/{securableItem}
Parameters
Type Name Description Schema
Path grain required The top level grain to return permissions for string
Path securableItem required The specific securableItem within the grain to return permissions for string
Responses
HTTP Code Description Schema
200 OK No Content
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Get a role by role name

GET /v1/roles/{grain}/{securableItem}/{roleName}
Parameters
Type Name Description Schema
Path grain required The top level grain to return permissions for string
Path roleName required The name of the role string
Path securableItem required The specific securableItem within the grain to return permissions for string
Responses
HTTP Code Description Schema
200 Role with specified name was found < RoleApiModel > array
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes a role

DELETE /v1/roles/{roleId}
Parameters
Type Name Description Schema
Path roleId required The id of the role string
Responses
HTTP Code Description Schema
204 Role with the specified id was deleted No Content
400 Invalid roled id provided Error
403 Client does not have access No Content
404 Role with specified id was not found No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Updates an existing role

PATCH /v1/roles/{roleId}
Parameters
Type Name Description Schema
Path roleId required The id of the role string
Body RolePatchApiRequest required The model containing the fields to update (currently only DisplayName and Description can be modified) RolePatchApiRequest
Responses
HTTP Code Description Schema
200 Updated RoleApiModel
403 Client does not have access No Content
404 Role with specified id does not exist Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Add permissions to an existing role

POST /v1/roles/{roleId}/permissions
Parameters
Type Name Description Schema
Path roleId required The id of the role string
Body List of permissions required The list of permissions to add to the role < PermissionApiModel > array
Responses
HTTP Code Description Schema
201 Permission added to role RoleApiModel
400 Invalid role id, no permissions specified to add, incompatible permission provided, or permission id was not provided Error
403 Client does not have access No Content
404 Role not found or permission not found Error
409 Permission with the specified id already exists for the role Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Delete permissions from an existing role

DELETE /v1/roles/{roleId}/permissions
Parameters
Type Name Description Schema
Path roleId required The id of the role string
Body List of permissions required The list of permissions to add to the role < PermissionApiModel > array
Responses
HTTP Code Description Schema
201 Permission removed from role RoleApiModel
400 Invalid role id or no permissions specified to delete from role Error
403 Client does not have access No Content
404 Role not found or permission not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Securable Item

Operations for managing Securable Items

Gets the top level securable item by client id

GET /v1/securableitems
Responses
HTTP Code Description Schema
200 OK SecurableItemApiModel
403 Client does not have access No Content
404 The client was not found by client id No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Gets a securable item by client id and securable item id

GET /v1/securableitems/{securableItemId}
Parameters
Type Name Description Schema
Path securableItemId required The id of the securable item string
Responses
HTTP Code Description Schema
200 OK SecurableItemApiModel
400 The securable item id must be a guid Error
403 Client does not have access No Content
404 The client was not found by client id or the securable item was not found No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Users

Operations related to user permissions

Adds a new user.

POST /v1/user
Parameters
Type Name Description Schema
Body User required The user to add UserApiModel
Responses
HTTP Code Description Schema
201 Created UserApiModel
400 User object in body failed validation Error
403 User does not have access No Content
409 User with specified IdentityProvider and Subject already exists Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets permissions for currently authenticated user

GET /v1/user/permissions
Responses
HTTP Code Description Schema
200 OK UserPermissionsApiModel
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Gets custom groups for a user

GET /v1/user/{identityProvider}/{subjectId}/groups
Parameters
Type Name Description Schema
Path subjectId required Subject ID (from external identity provider) string
Responses
HTTP Code Description Schema
200 List of GroupUserApiModel entities representing groups in which the user belongs < GroupUserApiModel > array
403 Client does not have access No Content
404 User was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Adds granular permissions for a user, either to allow or deny

POST /v1/user/{identityProvider}/{subjectId}/permissions
Parameters
Type Name Description Schema
Path identityProvider required External identity provider name string
Path subjectId required Subject ID (from external identity provider) string
Body GranularPermissions required The permissions to add for the user. < PermissionApiModel > array
Responses
HTTP Code Description Schema
204 Granular permissions were added No Content
400 No permissions to add included in request. No Content
403 Client does not have access No Content
409 The permissions specified already exist either as duplicates or with a different permission action than the one specified or a permission is in the request as both allow and deny No Content
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.manageclients

Gets permissions for specified user. Note this will only retrieve 1) granular permissions and 2) permissions under roles mapped to Custom groups.

GET /v1/user/{identityProvider}/{subjectId}/permissions
Parameters
Type Name Description Schema
Path identityProvider required External identity provider name string
Path subjectId required Subject ID (from external identity provider) string
Responses
HTTP Code Description Schema
200 OK < ResolvedPermissionApiModel > array
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes granular permissions for a user

DELETE /v1/user/{identityProvider}/{subjectId}/permissions
Parameters
Type Name Description Schema
Path identityProvider required External identity provider name string
Path subjectId required Subject ID (from external identity provider) string
Body GranularPermissions required The permissions to delete from the user. < PermissionApiModel > array
Responses
HTTP Code Description Schema
204 The permissions were deleted No Content
400 No permissions were specified or the permissions specified do not exist or already exist with a different permission action. No Content
403 Client does not have access No Content
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.manageclients

Adds roles to an existing user.

POST /v1/user/{identityProvider}/{subjectId}/roles
Parameters
Type Name Description Schema
Body Roles required The roles to add < RoleApiModel > array
Responses
HTTP Code Description Schema
200 Roles added. UserApiModel
400 List of roles in body failed validation Error
403 User does not have access to add the specified roles. No Content
404 Specified user does not exist Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write

Gets the roles associated with a user

GET /v1/user/{identityProvider}/{subjectId}/roles
Parameters
Type Name Description Schema
Path identityProvider required External identity provider name string
Path subjectId required Subject ID (from external identity provider) string
Responses
HTTP Code Description Schema
200 List of roles representing the roles this user has been directly associated to. < RoleApiModel > array
403 Client does not have access No Content
404 User was not found Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.read

Deletes roles from existing user.

DELETE /v1/user/{identityProvider}/{subjectId}/roles
Parameters
Type Name Description Schema
Body Roles required The roles to delete. < RoleApiModel > array
Responses
HTTP Code Description Schema
200 Roles deleted. UserApiModel
400 List of roles in body failed validation Error
403 User does not have access to add the specified roles. No Content
404 Specified user does not exist Error
415 Content-Type header was not included in request Error
Security
Type Name Scopes
Unknown Oauth2 fabric/authorization.write