Logging into the Runtime API

Log in as a user

Open api.microbiomedata.org/docs and click on the "Authorize" button located above the list of endpoints:

In the modal dialog that appears, locate the section entitled "User login" and—in that section—enter your username and password, then click the "Authorize" button located below those fields.

When you are logged in, the "username" field will turn into read-only text and the "password" field will turn into asterisks, as shown here:

Once you're logged in, click the "Close" button to close the modal and return focus to the API documentation.

Create a user

Important: Only Runtime administrators (i.e. Runtime users that are admins of the special site named "nmdc-runtime-useradmin") can create users.

Go to POST /users, and click the Try it out button. In the request body, the only required fields are username and password. If you know the ids of any sites you would like the new user to administer, enter those as an array value for the site_admin field.

Share the new user's password securely with them. For example, a free instance of the open-source snappass web app is hosted by Polyneme at snappass.polyneme.xyz. This will generate a one-time link that you can email, send via Slack message, etc. to the new user.

Create a site client

If you administer one or more sites, you can generate credentials for a site client that will act on behalf of the site. This is used for managing certain API resources—rather than an individual person being responsible for a resource, a site is responsible for it, allowing for users that administer that site to "come and go" over time.

Once logged in, you can use GET /users/me to see the ids of sites you can administer. Example response:

{
  "username": "alice_the_admin",
  "site_admin": [
    "alice-laptop",
    "nmdc-runtime-useradmin"
  ]
}

{
  "username": "bob_the_bioinformatician",
  "site_admin": [
    "bob-laptop"
  ]
}

You can create a site via POST /sites. If the id you request is already in use (i.e. already exists), you will get an error response. We suggest ignoring capability_ids for now; that can be populated later.

Once you have identified the site you want to generate credentials for, you can use the POST /sites/{site_id}:generateCredentials endpoint to do so. The response will contain the credentials for the generated site client, which will look something like this:

{
  "client_id": "sys0***",
  "client_secret": "***"
}

Store these two values securely for future use. Treat the client_secret value, specifically, like you would treat a password.

Log in as a site client

Now that you have site client credentials, you can log in as the associated site.

Open api.microbiomedata.org/docs and click on the "Authorize" button located above the list of endpoints:

In the modal dialog that appears, if any sections show that you are already logged in, click the "Logout" button in each of those sections before continuing.

Next, locate the section entitled "Site client login" and—in that section—enter your client_id and client_secret values, then click the "Authorize" button located below those fields.

You are now logged in as a site client.