SenSeeAct Documentation

# Access controller (/access)

This controller contains endpoints to control access to data of other users and permissions to call endpoints. The access control endpoints can be divided in three groups.

The first group of endpoints allows users to grant access to (parts of) their own data to other users.

/access/project/{project} (POST)
/access/project/{project} (DELETE)
/access/project/{project}/grantee/list (GET)
/access/project/{project}/modules (GET)
/access/project/{project}/subject/list (GET)

Using the second group of endpoints, admins can give users with role PROFESSIONAL full access to their subjects.

/access/subject/list
/access/subject (POST)
/access/subject (DELETE)

The third group of endpoints allow admins to grant more fine-grained specific permissions to other users.

/access/permission/list
/access/permission (POST)
/access/permission (DELETE)
/access/permission/all (DELETE)

# /project/{project}/modules

/access/project/{project}/modules GET
Description
Returns the data modules and tables for which data access can be granted to other users in the specified project.
Authorization
Users need to have access to the specified project. Admins can access all projects.
URL parameters
{project}
Project code (see

/project/list

)
Content
–
Response (application/json)
JSON array with modules. Each module is a JSON object with the following properties:
name
Module name
tables
Array with table names
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/access/project/default/modules
X-Auth-Token: ...
Response 
[
    {
        "name": "activity",
        "tables": [
            "steps"
        ]
    }
]

# /project/{project}/grantee/list

/access/project/{project}/grantee/list GET
Description
Returns all grantees and access rules for the specified subject within a project. That is all users who were granted access to data of the subject, along with the access rules.
Authorization
Users need to have access to the specified project. Admins can access all projects.
All users can get grantees of their own data within a project that they can access.
Patients can only get grantees of their own data.
Professionals can get grantees of data of users to whom they were granted access.
Admins can get grantees of any user.
URL parameters
{project}
Project code (see

/project/list

)
subject
(optional) User ID of the user whose grantees should be returned. Omit or leave empty to get grantees of your own data.
Content
–
Response (application/json)
JSON array with grantees and access rules. Each element is a JSON object with the following properties:
grantee
Object with information about the grantee
accessRestriction
Array with access restrictions, or null if full access was granted. If an array is specified, it should contain at least one restriction.
A grantee is a JSON object with the following properties. This may later be changed to other user profile fields.
userid
User ID
email
Email address
emailVerified
true if the email address has been verified, false otherwise. This is currently always false.
An access restriction is a JSON object with the following properties:
module
Module name (see

/access/project/{project}/modules

)
accessMode
r (read only), w (write only), rw (read and write)
start
Start date formatted as 2021-02-01, or null
end
End date formatted as 2021-02-01, or null
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/access/project/default/grantee/list
    ?subject=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
[
    {
        "grantee": {
            "userid": "c86901659f5a428f94022190414927cd",
            "email": "grantee1@example.com",
            "emailVerified": false
        },
        "accessRestriction": [
            {
                "module": "activity",
                "accessMode": "r",
                "start": "2021-02-01",
                "end": null
            }
        ]
    },
    {
        "grantee": {
            "userid": "2607180a921b4ed8a5f1924580357319",
            "email": "grantee2@example.com",
            "emailVerified": false
        },
        "accessRestriction": null
    }
]

# /project/{project}/subject/list

/access/project/{project}/subject/list GET
Description
Returns all subjects and access rules for the specified grantee within a project. That is all users who granted access to their data, along with the access rules.
Authorization
Users need to have access to the specified project. Admins can access all projects.
All users can get subjects of themselves within a project that they can access.
Patients can only get subjects of themselves.
Professionals can get subjects of users to whom they were granted access.
Admins can get subjects of any user.
URL parameters
{project}
Project code (see

/project/list

)
grantee
(optional) User ID of the grantee whose subjects should be returned. Omit or leave empty to get your own subjects.
Content
–
Response (application/json)
JSON array with subjects and access rules. Each element is a JSON object with the following properties:
subject
Object with information about the subject
accessRestriction
Array with access restrictions, or null if full access was granted. If an array is specified, it should contain at least one restriction.
A subject is a JSON object with the following properties. This may later be changed to other user profile fields.
userid
User ID
email
Email address
An access restriction is a JSON object with the following properties:
module
Module name (see

/access/project/{project}/modules

)
accessMode
r (read only), w (write only), rw (read and write)
start
Start date formatted as 2021-02-01, or null
end
End date formatted as 2021-02-01, or null
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/access/project/default/subject/list
    ?grantee=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
[
    {
        "subject": {
            "userid": "c86901659f5a428f94022190414927cd",
            "email": "subject1@example.com"
        },
        "accessRestriction": [
            {
                "module": "activity",
                "accessMode": "r",
                "start": "2021-02-01",
                "end": null
            }
        ]
    },
    {
        "subject": {
            "userid": "2607180a921b4ed8a5f1924580357319",
            "email": "subject2@example.com"
        },
        "accessRestriction": null
    }
]

# /project/{project} (POST)

/access/project/{project} POST
Description
Defines an access rule between a grantee and subject. This endpoint grants the grantee access to data of the subject. It replaces any previous access rule for the same project, grantee and subject.
Authorization
Users need to have access to the specified project. Admins can access all projects.
All users can grant access to their own data within a project that they can access.
Patients can only grant access to their own data.
Professionals can can grant access to data of users to whom they were granted access.
Admins can grant access to data of any user.
URL parameters
{project}
Project code (see

/project/list

)
granteeEmail
Email address of the grantee
subject
(optional) User ID of the subject. Omit or leave empty for yourself.
Content
JSON object with the following property:
accessRestriction
Array with access restrictions, or null if full access was granted. If an array is specified, it should contain at least one restriction.
An access restriction is a JSON object with the following properties:
module
Module name (see

/access/project/{project}/modules

)
accessMode
r (read only), w (write only), rw (read and write)
start
Start date formatted as 2021-02-01, or null
end
End date formatted as 2021-02-01, or null
Response (application/json)
–
Errors
If the grantee user with the specified email address was not found
HTTP status
404 Not Found
Code
USER_NOT_FOUND
Example
Request 
POST https://www.example.com/servlets/senseeact/v6.1.0/access/project/default
    ?granteeEmail=grantee@example.com
    &subject=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
 
{
    "accessRestriction": [
        {
            "module": "activity",
            "accessMode": "r",
            "start": "2021-02-01",
            "end": null
        }
    ]
}
Response 
–

# /project/{project} (DELETE)

/access/project/{project} DELETE
Description
Deletes an access rule between a grantee and subject. This endpoint revokes access to data of the subject.
Authorization
Users need to have access to the specified project. Admins can access all projects.
All users can revoke access to their own data within a project that they can access.
Patients can only revoke access to their own data.
Professionals can can revoke access to data of users to whom they were granted access.
Admins can revoke access to data of any user.
URL parameters
{project}
Project code (see

/project/list

)
grantee
User ID of the grantee
subject
(optional) User ID of the subject. Omit or leave empty for yourself.
Content
–
Response
–
Example
Request 
DELETE https://www.example.com/servlets/senseeact/v6.1.0/access/project/default
    ?grantee=b43f784d76c44e7a9ae0370b91521753
    &subject=c86901659f5a428f94022190414927cd
X-Auth-Token: ...
Response 
–

# /subject/list

/subject/list GET
Description
Returns all users that you or the specified user have been given access to with

POST /access/subject

. If you are not an admin, you can only get the subjects for yourself. Admins can also get the subjects users of other users.
Authorization
Patients cannot call this endpoint.
Professionals can only get their own subjects.
Admins can get the subjects of any user.
URL parameters
user
(optional) User ID of the user whose subjects you want to get. Omit or leave empty to get your own subjects. Only admins can get the subjects of another user.
includeInactive
(optional) true if you want to include inactive users, false if you only want to get active users. The default is true.
Content
–
Response (application/json)
JSON array with user objects for the subjects. For the complete description of a user object, see

GET /user/

.
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/access/subject/list
    ?user=b43f784d76c44e7a9ae0370b91521753&includeInactive=true
X-Auth-Token: ...
Response 
[
    {
        "userid": "f6d9f1f15e4b41769db3b0565ba6e788",
        "email": "patient01@example.com",
        "role": "PATIENT",
        ...
    },
    ...
]

# /subject (POST)

/user/subject POST
Description
Adds a patient subject to a professional user. This means that the professional is granted full access to the patient.
Authorization
Only admins can call this endpoint.
URL parameters
user
User ID of the professional. This must be a user with role PROFESSIONAL.
subject
User ID of the patient. This must be a user with role PATIENT.
Content
–
Response
–
Example
Request 
POST https://www.example.com/servlets/senseeact/v6.1.0/user/subject
    ?user=prof@example.com
    &subject=patient@example.com
X-Auth-Token: ...
Response 
–

# /subject (DELETE)

/user/subject DELETE
Description
Removes a patient subject from a professional user. This revokes the access that was granted with

POST /access/subject

.
Authorization
Only admins can call this endpoint.
URL parameters
user
User ID of the professional. This must be a user with role PROFESSIONAL.
subject
User ID of the patient. This must be a user with role PATIENT.
Content
–
Response
–
Example
Request 
DELETE https://www.example.com/servlets/senseeact/v6.1.0/user/subject
    ?user=prof@example.com
    &subject=patient@example.com
X-Auth-Token: ...
Response 
–

# /permission/list

/permission/list GET
Description
Returns the list of permissions granted to the specified user.
Authorization
All users can access their own permissions.
Patients can only access their own permissions.
Professionals can access the users to whom they were granted access.
Admins can access all users.
URL parameters
user
(optional) User ID of the user whose permissions should be returned. Omit or leave empty to get your own permissions.
Content
–
Response
JSON array with permissions. Each record is a JSON object with the following properties:
id
UUID
user
User ID
permission
The permission name (see below).
params
JSON object with parameters for the permission. This depends on the type of permission (see below).
Below is a list of currently supported permissions and their parameters.

write_resource_table

Allows users to write records to a ‘resource table’, that is a project table without a user field. This kind of tables is used for general project resources. Parameters:
project
Project code (see

/project/list

)
table
Table name, or * for all tables.
Example
Request 
GET https://www.example.com/servlets/senseeact/v6.1.0/access/permission/list
    ?user=b43f784d76c44e7a9ae0370b91521753
X-Auth-Token: ...
Response 
[
    {
        "id": "9711fecf05964076a343d6d26cebe889",
        "user": "b43f784d76c44e7a9ae0370b91521753",
        "permission": "write_resource_table",
        "params": {
            "project": "default",
            "table": "questionnaires"
        }
    },
    ...
]

# /permission (POST)

/permission POST
Description
Grants a permission to a user.
Authorization
Only admins can call this endpoint.
URL parameters
user
User ID of the user to whom the permission should be granted.
permission
The permission name (see

/permission/list

)
Content
JSON object with parameters for the permission. This depends on the type of permission (see

/permission/list

)
Response
–
Example
Request 
POST https://www.example.com/servlets/senseeact/v6.1.0/access/permission
    ?user=b43f784d76c44e7a9ae0370b91521753
    &permission=write_resource_table
X-Auth-Token: ...
 
{
    "project": "default",
    "table": "questionnaires"
}
Response 
–

# /permission (DELETE)

/permission DELETE
Description
Revokes a permission that was granted to a user. This endpoint only revokes the permission with the same name and parameters as specified.
Authorization
Only admins can call this endpoint.
URL parameters
user
User ID of the user from whom the permission should be revoked.
permission
The permission name (see

/permission/list

)
Content
JSON object with parameters for the permission. This depends on the type of permission (see

/permission/list

)
Response
–
Example
Request 
DELETE https://www.example.com/servlets/senseeact/v6.1.0/access/permission
    ?user=b43f784d76c44e7a9ae0370b91521753
    &permission=write_resource_table
X-Auth-Token: ...
 
{
    "project": "default",
    "table": "questionnaires"
}
Response 
–

# /permission/all (DELETE)

/permission/all DELETE
Description
Revokes all permissions with the specified name from a user.
Authorization
Only admins can call this endpoint.
URL parameters
user
User ID of the user from whom the permissions should be revoked.
permission
The permission name (see

/permission/list

)
Content
–
Response
–
Example
Request 
DELETE https://www.example.com/servlets/senseeact/v6.1.0/access/permission/all
    ?user=b43f784d76c44e7a9ae0370b91521753
    &permission=write_resource_table
X-Auth-Token: ...
Response 
–

← /project (general) →