Skip to content

Home

Jump to bottom
gerome12 edited this page Apr 20, 2021 · 70 revisions

Authentication Server API Documentation

Documentation of the KHEOPS REST API. Most of this API is implemented within the Authorization Server

The following API's are available to clients at the /api root

The APIs are based on the following speifications.

Relevant RFCs

Core OAuth 2.0

OAuth 2.0 Grant Requests from Assertions

Other

Relevant DICOMweb Specifications

OpenID Connect / OAuth2

KHEOPS behaves as an OpenID Connect (OIDC) Relying Party (RP) and delegates user authentication to an OpenID Connect Provider (OP).

In the context of the Report Providers API KHEOPS behaves as an OP and issues tokens to Report Providers using OIDC APIs.

Kheops front-ends can use the OAuth2 /token endpoint to issue viewer tokens, which are Access Tokens that serve to encrypt, encapsulate, and reduce the priviledges of another Access Token. These tokens are meant to be transmitted to third-party viewer applications, for example, to provide tokens that can be used only to access a specific study within a specific album.

Study List

KHEOPS implements the DICOMweb API. It is possible to pass additional query parameters to the following DICOMweb resources to specify whether it is a specific album or the inbox that should be queried.

  • Get a list of studies : GET /studies
    Requires an Access Token with the user as the sub claim.

    Without specific non-QIDO parameters, this resource will return all studies the user has access to, including the user's Inbox, and all studies within Albums the user has access to.

Study-level metadata WADO-RS queries follow the WADO-RS specification.

  • Get metadata for a study : GET /studies/{studyInstanceUID}/metadata
    Requires an Access Token with the user as the sub claim.

    Will return metadata for the series the user has access to.

Studies/Series Favorites

Working with the Inbox

While these resources are very similar in appearance to STOR-RS resources, they don't accept DICOM objects, and should be considered to be entirely different.

  • Give a user access to a study (send) : PUT /studies/{StudyInstanceUID}/users/{user}
    Requires an Access Token with a sub claim that specifies a user who has access to at least one series in the study.

    This resource can be used by a user that has access to at least one series of the specified study to share all accessible series with another user.

  • Give a user access to a specific series (send) : PUT /studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/users/{user}
    Requires an Access Token with a sub claim of a user that has access to the specified series, or an Access Token with the user as the sub claim.

    This resource can be used by a user that has access to a series to send the series to another user.

  • Give a user access to a specific series (self appropriate) : PUT /studies/{StudyInstanceUID}/series/{SeriesInstanceUID}
    Requires an Access Token with a sub claim of a user that has access to the specified series, or an Access Token with the user as the sub claim.

    This resource can be used by a user to claim access to a series UID that is unknown to the authorization server. The user will then be able to get an Access Token that can be used to do an STOW-RS to the DICOMweb server.

  • Remove a study from the Inbox : DELETE /studies/{StudyInstanceUID}
    Requires an Access Token with the user as the sub claim.

    Relinquishes access to all series in the specified study.

  • Remove a specific series from the Inbox : DELETE /studies/{StudyInstanceUID}/series/{SeriesInstanceUID}
    Requires an Access Token with the user as the sub claim.

    Relinquishes access to the specified series.

  • Get comments about a study : GET /studies/{StudyInstanceUID}/comments
    Requires an Access Token with the user as the sub claim.

  • Post a comment about a study : POST /studies/{StudyInstanceUID}/comments
    Requires an Access Token with the user as the sub claim.

DICOMweb Capability Tokens

A DICOMweb proxy will provide access to a specific user's content using a service URL that will identify a specific user. For the time being this proxy will be built into the Authenitication Server, but in time it may be moved to it's own server. These resources give the user the ability to manage Capability Tokens.

Webhooks

Working with Albums

Albums are groups of series.

  • Get a list of albums : GET /albums
    Requires an Access Token with the user as the sub claim.

  • Get metadata for an album : GET /albums/{album_id}
    Requires an Access Token with the user as the sub claim. The user must be an user or an admin.

  • Create an album : POST /albums
    Requires an Access Token with a user specified as the sub claim.

    The user who creates the album is automatically set as admin.

  • Edit an album : PATCH/albums/{album_id}
    Requires an Access Token with a user specified as the sub claim.

  • Delete an album : DELETE /albums/{album_id}
    Requires an Access Token with admin access to the album.

  • Add a study : PUT/studies/{StudyInstanceUID}/albums/{album_id}
    Requires an Access Token with admin access to the album or with write permission.

  • Add a series : PUT/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/albums/{album_id}
    Requires an Access Token with admin access to the album or with write permission.

  • Remove a study : DELETE /studies/{StudyInstanceUID}/albums/{album_id}
    Requires an Access Token with admin access to the album or with write permission.

  • Remove a series : DELETE /studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/albums/{album_id}
    Requires an Access Token with admin access to the album or with write permission.

  • Retrieve studies using the study list resource. here

  • Add a user : PUT /albums/{album_id}/users/{user}
    Requires an Access Token with admin access to the album or with "addUser" permission.

  • Remove a user : DELETE /albums/{album_id}/users/{user}
    Requires an Access Token with admin access to the album, or an Access Token with the user as the sub claim.

  • Get the list of users : GET /albums/{album_id}/users
    Requires an Access Token with access to the album.

  • Add and upgrade an user to Admin : PUT /albums/{album_id}/users/{user}/admin
    Requires an Access Token with admin access to the album.

  • Downgrade an admin to User : DELETE /albums/{album_id}/users/{user}/admin
    Requires an Access Token with admin access to the album.

  • Add an album to favorites : PUT/albums/{album_id}/favorites
    Requires an Access Token with access to the album.

  • Remove an album from favorites : DELETE /albums/{album_id}/favorites
    Requires an Access Token with access to the album.

  • Post a comment : POST /albums/{album_id}/comments
    Requires an Access Token with admin access to the album or with "writeComment" permission.

  • Get a list of events (comments and/or mutations) : GET /albums/{album_id}/events
    Requires an Access Token with access to the album.

Others

  • User info : GET /users
    Requires an Access Token with user access.

  • Inbox info : GET /inboxinfo
    Requires an Access Token with user access.

Report Providers

Home

Clone this wiki locally