Introduction

Creating institutional accounts via the API is a method for easily creating manual accounts in cases where the HR Feed or account creation at 1st login processes aren’t suitable or possible. Even though any API client might be used for creating such accounts, the purpose of this document is to provide a simpler and faster way of creating an account without the prerequisites of needing too much programming knowledge by using the Figshare documentation, available at https://docs.figshare.com.

Before starting 

As these accounts can be created on both staging (figsh.com) and production (figshare.com) environments, this document will refer only to the production environment. If the staging environment is needed, the API documentation resides under https://docs.figsh.com and the token needs to be generated from the staging institutional admin account. 

Steps

In order to manually create an institutional Figshare account, the following steps need to be followed:

Step 1 

Generate a Personal Figshare token from an institutional Figshare account which has institutional administration privileges. This value can be retrieved by accessing the Account Menu and selecting the Applications option from the dropdown. You may find more on how a personal token is created at the following link: https://help.figshare.com/article/how-to-get-a-personal-token. Once the value is retrieved, please store it in a secure place, as you won’t have the chance to see it again.

Step 2 

Open the Figshare API documentation on the Create a new institutional account API endpoint page, according to the environment used. The link resides to  https://docs.figshare.com/#private_institution_accounts_create , but it can be also accessed by opening the https://docs.figshare.com link, followed by selecting the following path: Institutions -> Create new institution account from the left-side menu.

Step 3 

Add the generated token to the Token section of the Figshare documentation page, available on the left-side corner of the page. See the attached image below: 


Step 4 

Fill the Account section with the required information. A sample dictionary with the needed values that can be added for the new account creation is displayed on the Body Sample area (right-side menu), together with the Body Schema (contains info such as whether the attribute is mandatory or not). A comprehensive description of these attributes is displayed below:

  • email: mandatory value. Represents the email address of the account which will be created. The provided email address needs to be valid
  • first_name: optional value. First name of the account owner
  • last_name: mandatory value. Last name of the account owner
  • group_id:  optional value. Without being specified, the user is created at the top-level group. There are 2 ways into which the group id can be retrieved:
    • Using the API specific endpoint: By using the private account institution groups endpoint, available at https://docs.figshare.com/#private_institution_groups_list
    • Through the administrator interface: by going to the configuration page for the group and getting the id from the URL (see example below):

  • institution_user_id: optional value. This value is required if the login needs to be performed via a Single Sign-On service 
  • symplectic_user_id: optional value. The Symplectic user id value associated with the account
  • quota: optional value. The amount of quota which will be allocated to the newly-created account in bytes. Without specifying this param, the quota value will be 0
  • is_active: optional value. Can have the true and false values. By default, the true value is applied  


Step 5

Complete the creation process by pressing the Try button, displayed under the Parameters section. If the 201 status code is returned, the account has been successfully created. A list of the possible response message values is also displayed below the Try button.

Log in considerations:

If the account had been created without the institution_user_id param, a forgot password procedure is needed under the institutional Figshare instance for password retrieval (for instance, for University of Amsterdam the URL is https://uvaauas.figshare.com/account/forgotpassword), while the log in needs to be performed under https://uvaauas.figshare.com/account/login page

If the account had been created with the institutional_user_id param, the log in needs to be performed by pressing the Login button on your institutional instance of Figshare. In this case, the forgot password procedure is not needed

An account can’t have an institution user id value and a password at the same time.


Updating manual accounts

If the created account needs to be updated, the https://docs.figshare.com/#private_institution_accounts_update endpoint can be used (only the active/inactive status and the group id values can be updated)

‍

If there are any issues or concerns regarding this matter, don’t hesitate to contact us by submitting a support ticket on our platform or send us an email at support@figshare.com.