Login and Logout

Logging in on the command line and using authentication tokens.

Logging In on the Command Line

You can use the command line interface (CLI) to log in to the DNAnexus Platform using the command dx login, at which point you will be prompted to select a project in which to work.
In the example below, the user "amy" has logged in and has 3 projects for which she has CONTRIBUTE or higher permissions. She can enter a number to select a project or press to work in the "SAM importer test" project. In this case, she has decided to work on "Scratch Project", so she enters "1".
$ dx login
Acquiring credentials from
Username: amy
Note: Use "dx select --level VIEW" or "dx select --public" to select from
projects for which you only have VIEW permissions.
Available projects (CONTRIBUTE or higher):
0) SAM importer test (CONTRIBUTE)
1) Scratch Project (ADMINISTER)
Pick a numbered choice [2]: 1
Setting current project to: Scratch Project

Logging Out on the Command Line

You can log out using dx logout.
$ dx logout
Deleting credentials from…
Please note that this command invalidates the authentication token used for the session, so if you used dx login --token <TOKEN> to log in and then use dx logout to log out, you will be unable to use <TOKEN> in future sessions.

Authentication Tokens

Generating an authentication token

You can log in without having to provide a username and password for a certain amount of time by using authentication tokens (henceforth referred to as tokens). Broadly, authentication tokens are generated by providing your username and password to the platform and specifying a time period for which the token may be used to log in.
If you provide your token to a third party, they may access the DNAnexus platform with your token, effectively impersonating you as a user. They will have the same access level as you for any projects to which the token has access, potentially allowing them to run jobs and incur charges to your account. Please keep your token safe and secure.
To generate a token, click My Profile in the dropdown menu that appears, when you click on your avatar at the far right end of the main Platform menu:
Once at your profile, navigate to the API Tokens tab and click on the New Token button.
This sequence of actions will bring you to the New Token window.
Fill out each field accordingly and select Generate Token.
A pop-up will then appear saying “Your token has been generated. Please copy it for later use; for security purposes, this is the only time you will see it:” with a 32-character token comprised of letters and numbers in the line below. Copy down this token in a secure location and save it for later.
Some examples in which tokens might be used include the following:
  • Writing a script. Tokens can be helpful when writing scripts that require logging in to the platform. However, if you incorporate a token into a script, the token should only be valid for as long as the script requires access to the platform; the "Expiration Date" field should be modified accordingly. Furthermore, the token should only be granted access to the projects required by the script. If your script uploads data to only one project, the "Token Scope" should reflect the limited access.
  • Logging in to the command line for interactive use. If your organization uses single sign-on and you cannot log in to the command line using a username and password, or if for any other reason you don't wish to log in to the command line with your username and password, tokens are quite useful. This is the only scenario in which you should use a full-scope token, thereby allowing you to access all of your available projects. Otherwise, tokens should be scoped according to the access level required.

Logging in with an authentication token

In order to use a token to log in on the command line, you must use dx login with the --token flag. If Alice had logged in earlier using a token instead, this is what she would have seen:
$ dx login --token
Note: Use "dx select --level VIEW" or "dx select --public" to select from
projects for which you only have VIEW permissions.
Available projects (CONTRIBUTE or higher):
0) SAM importer test (CONTRIBUTE)
1) Scratch Project (ADMINISTER)
Pick a numbered choice [2]: 1
Setting current project to: Scratch Project

Revoking authentication tokens

You must navigate to the API tokens tab of your profile in order to revoke a token.
Once in the API tokens tab, select which token you wish to revoke and then click the Revoke button:
Once you confirm that you wish to revoke the token, the token will be revoked.
Some examples in which tokens might be revoked include the following:
  • Token accidentally shared too widely. If more people have access to your token than you would like, revocation of the token will cut off access to your account by unwanted parties.
  • Token no longer needed. For example, if the script utilizing the token is no longer in use; or if the group granted access to the platform using the token no longer exist; or in any other instance in which the token is no longer necessary, you should revoke it to restrict access to your account.

Logging In Non-Interactively

The standard way of logging in on the CLI requires interaction with the terminal in order to both log in and select a project with which to work for the session. However, for scripts and other scenarios in which interacting with the terminal proves impractical, logging in non-interactively is possible.
In order to log in non-interactively, you must use dx login with the --token flag. You can include the --no-projects flag if you wish to refrain from selecting a project, or you can use the the dx select command to select a project automatically.
If Alice were to log in non-interactively, this is what she would see:
$ dx login --token --noprojects
$ dx login --token ; dx select project-xxxx
Selected project project-xxxx

Two-Factor Authentication

Two-Factor Authentication is an easy-to-use system that allows you to add an extra layer of security protecting the data stored on the DNAnexus platform.
After enabling Two-Factor Authentication, in addition to entering your username and password at login, you will also be required to enter a two-factor authentication code to access your account. This code is generated by a third-party two-factor authentication application (i.e. Google Authenticator) and is a time-based one-time password that will only be valid for that login session.
With Two-Factor Authentication protecting your account, your data will be protected even in the case that both your username and password are stolen. The attacker will be unable to access your account without your two-factor authentication code which is generated on your smartphone or computer.

Enabling two-factor authentication

To enable two-factor authentication, select Account Security from the dropdown menu accessible via your avatar, at the far right end of the main menu:
In the Account Security tab, click the button labeled Enable 2FA, then follow the instructions, to select and set up a third-party app, to generate tokens used for two-factor authentication.
After successfully enabling two-factor authentication, you will be redirected to a page containing back-up codes which can be used in place of an application-generated two-factor authentication code. We recommend you save these codes in a secure place in case you are unable to access your authentication application.
We recommend using Google Authenticator on your mobile device. It's a popular, free solution available on Apple iOS and Android mobile devices. Get it on Google Play or from the Apple iTunes App Store.
We currently do not support sending authentication codes via text message (SMS). If you are unable to use a smart phone application, compatible two-factor authentication apps, which use the TOTP (Time-based One-time Password) algorithm, exist for other platforms. Let us know if you have a favorite app or other feedback about using this feature by contacting our support team.


Once two-factor authentication is enabled on your account, you will be required to enter the application-generated two-factor authentication code in addition to your username and password at every login regardless if you are using the web platform or command-line interface. You will also be required to enter a code to change personal information.
Specifically, you will need a two-factor authentication code to do the following:
  • Access your account through DNAnexus web platform
  • Change your password
  • Change your user settings
  • Turn off two-factor authentication
  • Login to your account using the DNAnexus Command Line Interface (CLI)
In the case you lose your phone or are otherwise unable to access your authenticator application, you can use the back-up codes provided when enabling Two-Factor Authentication to access your account. If this is not an option, please contact our support team for further assistance.

Disabling two-factor authentication

We highly recommend you protect the data you store on DNAnexus with two-factor authentication. However, if you change your mind, you can always turn it off simply by going back to your Profile page and turning off two-factor authentication on the User Account tab in Security Settings. You will be required to enter your password and your two-factor authentication code one more time to disable this feature.
If you disable two-factor authentication, then re-enable the feature, you will need to re-configure your TOTP application by scanning the new QR code or entering the new Secret Key. You will also be required to save the new back-up codes. The old back-up codes and codes generated by your previous application configuration will not be valid.
Last modified 1yr ago