Creating Accounts

NOTE: if you follow the instructions in the bootstrapping document, you should have the three bootstrap accounts you need to run integration tests against Bridge successfully. You will not need to follow this document.

When you [bootstrap] Bridge for the first time, it will create a test study, but no accounts. This guide goes over creating the initial admin account, as well as creating other accounts (dev, researcher, worker, consented users).

Creating the initial admin account

1. Using an HTTP tool such as Postman, make a POST /v3/auth/signUp to Bridge server:

    {
      "appId":"api",
      "email":"[email protected]",
      "password":"n0t_a_r3al_p@ssword"
    }
   

   Substituting [email protected] with your email address, of course.

2. This will send a verification email to the given email address. Check that email and click the link to verify the account.

3. Unfortunately, in order to grant admin privileges, you have to already have admin privileges. Fortunately, you can always grant admin privileges through the database. Connect to the database and run the query select id from Accounts where studyId='api' and email='[email protected]' (again, substituting your email address).

4. Run the query insert into AccountRoles (accountId, role) values ('1a6WYXGWXByTb8tsSXS8l1', 'ADMIN'), substituting the account ID from the previous step.

Your account now has admin privileges. And now that you have admin privileges, you can create more admin accounts using the steps in the next session.

Note: Most admin account APIs are global. As such, you generally don't need to make admin accounts for each study, and you definitely should not create an admin account on a production server for anyone outside of Sage.

Note: See https://sagebionetworks.jira.com/browse/BRIDGE-1999 for long-term plans to bootstrap the initial admin user without requiring direct DB access.

Creating privileged accounts

1. Using an HTTP tool such as Postman, sign in to your Bridge Server with your admin account. This can be done using POST /v3/auth/signIn:

    {
      "appId":"api",
      "email":"[email protected]",
      "password":"n0t_a_r3al_p@ssword"
    }
   

   Note that this looks identical to the signUp request.

2. Then make the following request as a POST /v3/users:

    {
      "email":"[email protected]",
      "roles":["WORKER"]
    }
   

   again, substituting [email protected] with a real email address.

   Valid roles are ADMIN, DEVELOPER, RESEARCHER, TEST_USERS (note the plural), or WORKER.

   WARNING: This creates the user as already verified. Don't use this method to create accounts for fake email addresses. Doing so will cause emails (consent, password reset, etc) to bounce, and this will hurt our rating with SES and make it harder to send emails in the future.

3. This creates the user, but they will have no password. You will need to send a password reset request. This can be done by making a request to Bridge using POST /v3/auth/requestResetPassword:

    {
      "appId":"api",
      "email":"[email protected]"
    }
   

   Once that user receives that email and resets their password, they will be able to sign in and use their account.

Creating Consented Participants

This step is primarily useful when a dev creates a test user for testing purposes. In the real world, sign-up and consent will be done through an app or a web portal.

1. Using an HTTP tool such as Postman, make a POST /v3/auth/signUp to Bridge server:

    {
      "appId":"api",
      "email":"[email protected]",
      "password":"n0t_a_r3al_p@ssword"
    }
   

   Again, substituting the email address with a real one. You can use the plus trick ([email protected], [email protected], etc) to associate multiple accounts to the same email address.

2. This will send a verification email to the given email address. Check that email and click the link to verify the account.

3. Sign in to Bridge server by making a POST /v3/auth/signIn request:

    {
      "appId":"api",
      "email":"[email protected]",
      "password":"n0t_a_r3al_p@ssword"
    }
   

   This will sign you in, and then throw a 412 Precondition Failed, which means you're not consented.

4. Consent by making a POST /v3/consents/signature request:

    {
      "name":"Eggplant McTester",
      "birthdate":"1997-03-09",
      "scope":"all_qualified_researchers"
    }
   

   Your account is now verified and consented.