API Access
About
This page provides information about the process for applying for permission to use the secure Databrary API.
Application process
For performance and security reasons, Databrary is restricting the number of authorized users who are permitted to use the secure API. Researchers who have a specific research need to use the secure API, should contact the Databrary team by email.
After the initial consultation, Databrary staff will ask researchers to provide the following information:
1. Rationale for requesting API access vs. web app
2. Information about the files to be uploaded (or downloaded) and the number of volumes to be created.
- How many files and what type(s) of files
- Total storage footprint
- How many volumes
3. Plans to share the data with the research community.
- For data being uploaded, when will the data be shared with the research community?
- For data being downloaded, are the data currently shared with the research community? If not, what is the timeline for sharing the data?
4. Available funding for the data deposit (relevant to data uploads only).
We are not yet requiring data deposit fees, but plan to do so in the near future. These would be in the neighborhood of $3,500/TB, a cost roughly equivalent to the 10-year storage cost on a cloud provider.
Priority will be given to applications that have funding to pay data deposit fees.
5. Which Databrary user account(s) require access.
This should be a minimal number. If a non-Authorized Investigator user will be the main person doing the work, then that person must be an Affiliate of an Authorized Investigator and will need read/write privileges on any volumes created.
Review & Approval
The Databrary team will review the application. If necessary, we will seek additional information from the applicant team.
If the application is approved, a Databrary system administrator will enable secure API access privileges to the account or accounts. Databrary will send an email notifying the applicant team once that had been done. That email will contain a link to a secure user agent parameter that must be specified in order to access the secure API.
Do not share the user agent, client id, or client secret with anyone.
Doing so could put your data and others’ data at-risk and violates the Databrary Access Agreement terms.
Databrary reserves the right to revoke secure API access at any time for any reason.
Databrary will make its best efforts to communicate with research teams about the timing and rationale of any revocation of API access so as to minimize disruptions to research.
Usage
Once Databrary has enabled the generation of secure API tokens for approved Databrary users, those users may proceed as indicated in this section.
1. Create a secure token
Users should log in to the application and visit their profile page at https://databrary.org/profile. Then, click on the edit (pencil) icon. See Figure 1 below.
From the edit profile page, select the API Access tab.
Then, press the Add application button at right.
Create an application by entering the name and time period. The default is 180 days. When the application details window appears, capture these credentials in a separate file.
2. Acquire user agent
Databrary staff will send you a link to a site where you can retrieve the secure user agent value You will need to store this securely and use it in your application.
2. Create and test your application
Additional information about the secure API specification is here.
Sample test scripts are also available for your use.