Topics:
Create your project
View project details
To view project details:
Edit configuration
To update project configuration:
(See below for more information on configuration items.)
Set up OAuth2 credentials and URLs
Go to your project detail page to get OAuth2 credentials. Use these
to set up your OAuth2 authorization process.
(Read more about OAuth2 authorization
setup below for more details.)
Test authorization with up to 20 test users.
Once you've set up your OAuth2 authorization process, you can test user
authorizations. (Note: your own account can be a test user too!)
Try sending users to the "enrollment URL" you've specified to test the entire process.
Test withdrawal/deauthorization and reauthorization
Members can immediately withdraw/deauthorize a project on their
connections management page.
You can reauthorize a project by returning to its "signup URL".
If a project changes requested permissions, new permissions will take effect only if/when a member has reauthorized the project.
Test API data access
If any test users have data from requested sources, it will
become accessible to your project. Check that
data access is working correctly.
Test messaging
If your project is planning to send messages to users, you can test this
feature by
sending messages to your test users.
Test data upload
If your project is planning to add or return data to member accounts,
you can test the
data upload process.
Review project guidelines.
Review our Activity
Guidelines and ensure your project has good security and responsible
data management practices before seeking project approval.
Request project approval.
Project approval is required to remove the 20 user cap. Once approved,
we'll share your project with Open Humans members. For approval, we require
any project classified as a "study" to have been reviewed and approved by
an Institutional Review Board or equivalent ethics board.
The project approval process is performed with feedback from the larger Open Humans community. Project approval is discussed publicly on our Discourse and project members are asked to weigh and ask questions to the project leads. A step-by-step guide can be found in our Approval How-To.
When you no longer wish to have new members join your project, edit your project's configuration to turn off "Active" status.
Study or activity?
Are you doing research? If so, you're a "study". We expect all studies
to have be approved by an Institutional Review Board (IRB) or equivalent
ethical review.
Non-study projects are also welcome, for example: data analysis tools, or projects to enable import of a certain type of data.
Project name
Your project will be listed with this name.
Leader(s) or Principal Investigator(s)
These will be listed in your project description.
Organization or Institution
This will be listed in your project description.
Academic or non-profit?
Select "yes" if your project's affiliation is academic or nonprofit.
This affects how your project is listed in Open Humans.
Contact email for your project
Members who wish to contact your project will use this email address.
If your project sends messages, this email will be the "reply-to" in the
emails members receive.
URL for general information about your project
Members who want more information about your project can follow this
URL to learn more.
Short description
This description will be displayed for members when your project is
listed.
Long description
A longer description for members. (Note: This field isn't currently in
use by our site, but might be later.)
Description of data you plan to upload to member accounts
Describe any data your project is planning to add or return, via upload
to the accounts of your project's members. Leave this blank if your
project doesn't plan to add or return data via Open Humans.
Active
Members can only join a project if it is "active". You should answer
"Yes" during development to enable testing the join & authorization
process.
When you wish to close a study enrollment (i.e. no new members may join), remove "active" status for your project.
Badge image
Badges should be circular images. Members that join your project will
have this badge displayed on their profile.
Request sources access
Select all data sources that you're requesting members to share with
your project. New and updated data held by members will be shared in an
ongoing manner as long as your project is authorized.
Are you requesting permission to message users?
Answer "Yes" if you want your project to be authorized to send messages.
Are you requesting Open Humans usernames?
Answer "Yes" if you want your project to have access to the usernames
of your project members. This implicitly enables access to anything the
user is publicly sharing on Open Humans.
Username information is also potentially sensitive and/or identifying. You might want to avoid username access to improve security and potentially facilitate IRB review.
To facilitate the use of the OAuth2 API we offer two Python packages:
django-open-humans,
a re-usable application for the Django web framework. It fully
implements our API methods along with the necessary logic for logging
people in and requesting permissions.
Its documentation explains how to install, setup and use the package.
open-humans-api,
a package that wraps all calls to the Open Humans API into
Python functions and additionally provides command-line interfaces
to directly interact with the API.
See the documentation for more details.
Of course, the API can also be accessed through the programming language of your choice without those packages. Below is a brief overview of how to use OAuth2 credentials and URLs to authorize a user from your app or website. If you're not familiar with OAuth2, we recommend you read the OAuth Wikipedia article and other online resources for general information about these processes.
Direct your user to the Authorization URL.
This URL should includethe following parameters:
"client_id" set to your Client ID
"response_type" set to "code"
For example, for the authorization URL
https://www.openhumans.org/direct-sharing/projects/oauth2/authorize/
and the client ID ABCDEFG1234567, you send your user to:
https://www.openhumans.org/direct-sharing/projects/oauth2/authorize/?client_id=ABCDEFGJ1234567&response_type=code
User returns with code.
If the user authorizes your project, Open Humans will send them back to
your "Redirect URL" with the parameter "code" set. For example, if your
redirect URL is https://www.example.com/authorize_openhumans
and the code is 123abc456def then we'll send the user to:
https://www.example.com/authorize_openhumans/?code=123abc456def
Your website or app will presumably know which user is associated with this code. You should immediately exchange the code for token data, which you'll store associated with your user's account.
Exchange the code for a token.
Your website or app needs to exchange the code for a more permanent token.
Do this immediately: the code will expire soon after it's shared.
Use your client ID and client secret as credentials for this transaction.
Make sure you do this securely (use https).
Use a POST request to the "access token URL" with the following data:
'grant_type' set to 'authorization_code'
'code' set to the value of the code you received
'redirect_uri' set to the same redirect URL you've specified in Open Humans
If everything is set correctly, the Open Humans website will return JSON data with values for 'access_token', 'refresh_token', and 'expires_in' (seconds). Keep this token and refresh token secure. The token can be used to access the OAuth2 project member API endpoint to retrieve this member's project member ID and other data.
For example, the following Python code fragment exchanges a code for token data. (This uses the requests library.)
import requests
data = {
'grant_type': 'authorization_code',
'code': received_code,
'redirect_uri': your_redirect_url
}
token_response = requests.post(
open_humans_access_token_url,
data=data,
auth=requests.auth.HTTPBasicAuth(
your_open_humans_client_id,
your_open_humans_client_secret
)
)
token_data = token_response.json()
access_token = token_data['access_token']
refresh_token = token_data['refresh_token']
seconds_before_expiration = token_data['expires_in']Another example code-for-token exchange in JavaScript, using the request library.
const request = require('request')
request.post(
{
url: 'https://www.openhumans.org/oauth2/token/',
auth: {
'user': clientID,
'pass': clientSecret
},
formData: {
'grant_type': 'authorization_code',
'code': code,
'redirect_uri': redirectURI
},
}, function(err, res) {
console.log(res.statusCode)
console.log(res.body)
})
How to refresh your token.
For security reasons, tokens expire after a period of time. To request
a fresh token, use a POST request to the "access token URL" with the
following data:
'grant_type' set to 'refresh_token'
'refresh_token' set to the refresh token you received
If everything is set correctly, the Open Humans website will return JSON data with a new 'access_token', 'refresh_token', and 'expires_in' (seconds).
A webhook can optionally be provided to automate handling when members leaving (deauthorize) an activity (for example, a request to erase personal data, to comply with GDPR). If provided, when a member leaves an activity a POST will be sent to that URL with JSON formatted data containing the following fields:
project_member_id: (string) identifying the project member performing deauthorization
erasure_requested: (true/false) whether the deauthorizing member is requesting the activity delete their personal data
timestamp: (string) ISO 8601 format timestamp of the deauthorization
A webhook secret can optionally be provided, to be used to verify that
incoming requests sent to the webhook are coming from Open Humans.
If provided, POSTs to the webhook will use the secret to provide an hmac-sha1
a verification signature via a custom X-OpenHumans-Webhooks-Signature
header. The value of this header is the string sha1= followed by
the hmac-sha1 hexdigest of the payload.
For example, the secret: abcdefghijklmnop
would be used in combination with a payload:{"project_member_id": "12345678", "erasure_requested": true, "timestamp": "2020-06-30T20:00:00.000000+00:00"}
to provide the following signature in the header: sha1=ebda5c0a38593a4350ad8401b7d8c8f1cd08ec67
# example Python code for generating this string
import hmac
key = 'abcdefghijklmnop'.encode('utf-8')
payload = '{"project_member_id": "12345678", "erasure_requested": true, "timestamp": "2020-06-30T20:00:00.000000+00:00"}'.encode('utf-8')
sig = 'sha1=' + hmac.hex
|
|
Contact Us |
Community Guidelines |
Terms of Use |
Data Use Policy
Continue with Facebook
Continue with Email