DNAnexus Documentation
APIDownloadsIndex of dx CommandsLegal
  • Overview
  • Getting Started
    • DNAnexus Essentials
    • Key Concepts
      • Projects
      • Organizations
      • Apps and Workflows
    • User Interface Quickstart
    • Command Line Quickstart
    • Developer Quickstart
    • Developer Tutorials
      • Bash
        • Bash Helpers
        • Distributed by Chr (sh)
        • Distributed by Region (sh)
        • SAMtools count
        • TensorBoard Example Web App
        • Git Dependency
        • Mkfifo and dx cat
        • Parallel by Region (sh)
        • Parallel xargs by Chr
        • Precompiled Binary
        • R Shiny Example Web App
      • Python
        • Dash Example Web App
        • Distributed by Region (py)
        • Parallel by Chr (py)
        • Parallel by Region (py)
        • Pysam
      • Web App(let) Tutorials
        • Dash Example Web App
        • TensorBoard Example Web App
      • Concurrent Computing Tutorials
        • Distributed
          • Distributed by Region (sh)
          • Distributed by Chr (sh)
          • Distributed by Region (py)
        • Parallel
          • Parallel by Chr (py)
          • Parallel by Region (py)
          • Parallel by Region (sh)
          • Parallel xargs by Chr
  • User
    • Login and Logout
    • Projects
      • Project Navigation
      • Path Resolution
    • Running Apps and Workflows
      • Running Apps and Applets
      • Running Workflows
      • Running Nextflow Pipelines
      • Running Batch Jobs
      • Monitoring Executions
      • Job Notifications
      • Job Lifecycle
      • Executions and Time Limits
      • Executions and Cost and Spending Limits
      • Smart Reuse (Job Reuse)
      • Apps and Workflows Glossary
      • Tools List
    • Cohort Browser
      • Chart Types
        • Row Chart
        • Histogram
        • Box Plot
        • List View
        • Grouped Box Plot
        • Stacked Row Chart
        • Scatter Plot
        • Kaplan-Meier Survival Curve
      • Locus Details Page
    • Using DXJupyterLab
      • DXJupyterLab Quickstart
      • Running DXJupyterLab
        • FreeSurfer in DXJupyterLab
      • Spark Cluster-Enabled DXJupyterLab
        • Exploring and Querying Datasets
      • Stata in DXJupyterLab
      • Running Older Versions of DXJupyterLab
      • DXJupyterLab Reference
    • Using Spark
      • Apollo Apps
      • Connect to Thrift
      • Example Applications
        • CSV Loader
        • SQL Runner
        • VCF Loader
      • VCF Preprocessing
    • Environment Variables
    • Objects
      • Describing Data Objects
      • Searching Data Objects
      • Visualizing Data
      • Filtering Objects and Jobs
      • Archiving Files
      • Relational Database Clusters
      • Symlinks
      • Uploading and Downloading Files
        • Small File Sets
          • dx upload
          • dx download
        • Batch
          • Upload Agent
          • Download Agent
    • Platform IDs
    • Organization Member Guide
    • Index of dx commands
  • Developer
    • Developing Portable Pipelines
      • dxCompiler
    • Cloud Workstation
    • Apps
      • Introduction to Building Apps
      • App Build Process
      • Advanced Applet Tutorial
      • Bash Apps
      • Python Apps
      • Spark Apps
        • Table Exporter
        • DX Spark Submit Utility
      • HTTPS Apps
        • Isolated Browsing for HTTPS Apps
      • Transitioning from Applets to Apps
      • Third Party and Community Apps
        • Community App Guidelines
        • Third Party App Style Guide
        • Third Party App Publishing Checklist
      • App Metadata
      • App Permissions
      • App Execution Environment
        • Connecting to Jobs
      • Dependency Management
        • Asset Build Process
        • Docker Images
        • Python package installation in Ubuntu 24.04 AEE
      • Job Identity Tokens for Access to Clouds and Third-Party Services
      • Enabling Web Application Users to Log In with DNAnexus Credentials
      • Types of Errors
    • Workflows
      • Importing Workflows
      • Introduction to Building Workflows
      • Building and Running Workflows
      • Workflow Build Process
      • Versioning and Publishing Global Workflows
      • Workflow Metadata
    • Ingesting Data
      • Molecular Expression Assay Loader
        • Common Errors
        • Example Usage
        • Example Input
      • Data Model Loader
        • Data Ingestion Key Steps
        • Ingestion Data Types
        • Data Files Used by the Data Model Loader
        • Troubleshooting
      • Dataset Extender
        • Using Dataset Extender
    • Dataset Management
      • Rebase Cohorts and Dashboards
      • Assay Dataset Merger
      • Clinical Dataset Merger
    • Apollo Datasets
      • Dataset Versions
      • Cohorts
    • Creating Custom Viewers
    • Client Libraries
      • Support for Python 3
    • Walkthroughs
      • Creating a Mixed Phenotypic Assay Dataset
      • Guide for Ingesting a Simple Four Table Dataset
    • DNAnexus API
      • Entity IDs
      • Protocols
      • Authentication
      • Regions
      • Nonces
      • Users
      • Organizations
      • OIDC Clients
      • Data Containers
        • Folders and Deletion
        • Cloning
        • Project API Methods
        • Project Permissions and Sharing
      • Data Object Lifecycle
        • Types
        • Object Details
        • Visibility
      • Data Object Metadata
        • Name
        • Properties
        • Tags
      • Data Object Classes
        • Records
        • Files
        • Databases
        • Drives
        • DBClusters
      • Running Analyses
        • I/O and Run Specifications
        • Instance Types
        • Job Input and Output
        • Applets and Entry Points
        • Apps
        • Workflows and Analyses
        • Global Workflows
        • Containers for Execution
      • Search
      • System Methods
      • Directory of API Methods
      • DNAnexus Service Limits
  • Administrator
    • Billing
    • Org Management
    • Single Sign-On
    • Audit Trail
    • Integrating with External Services
    • Portal Setup
    • GxP
      • Controlled Tool Access (allowed executables)
  • Science Corner
    • Scientific Guides
      • Somatic Small Variant and CNV Discovery Workflow Walkthrough
      • SAIGE GWAS Walkthrough
      • LocusZoom DNAnexus App
      • Human Reference Genomes
    • Using Hail to Analyze Genomic Data
    • Open-Source Tools by DNAnexus Scientists
    • Using IGV Locally with DNAnexus
  • Downloads
  • FAQs
    • EOL Documentation
      • Python 3 Support and Python 2 End of Life (EOL)
    • Automating Analysis Workflow
    • Backups of Customer Data
    • Developing Apps and Applets
    • Importing Data
    • Platform Uptime
    • Legal and Compliance
    • Sharing and Collaboration
    • Product Version Numbering
  • Release Notes
  • Technical Support
  • Legal
Powered by GitBook

Copyright 2025 DNAnexus

On this page
  • Username (Handle) vs. User ID
  • API Method: /user-xxxx/describe
  • Specification
  • Inputs
  • Outputs
  • Errors
  • API Method: /user-xxxx/update
  • Specification
  • Inputs
  • Outputs
  • Errors

Was this helpful?

Export as PDF
  1. Developer
  2. DNAnexus API

Users

Learn about creating and managing users via the DNAnexus Platform API.

Last updated 1 year ago

Was this helpful?

Users can create their own DNAnexus user accounts by registering via the . For orgs covered by a license that enables account provisioning, org admins can create accounts for other users on behalf of the org.

For more information on a license that enables account provisioning by org admins, .

There are two API methods for interacting with existing users, one for describing existing users, and one for updating your own account details and settings.

Username (Handle) vs. User ID

When a user account is created, the user supplies their desired username (also referred to as handle). To transform this username into a user object ID, the username is lowercased, and the string "user-" is prepended to it. The username can be obtained from the user ID with the /user-xxxx/describe method below.

API Method: /user-xxxx/describe

Specification

Describes the specified user. Note that the list of projects billed to the user is not the same as the list of projects the user has permissions to. To retrieve the latter, use .

When /user-xxxx/describe is invoked by any user other than user-xxxx, or by a non full-scope token, only the ID, class, first, middle, last, and handle fields are returned.

Inputs

  • defaultFields boolean (optional, default false if fields is supplied, true otherwise) whether to include the default set of fields in the output (the default fields are described in the "Outputs" section below). The selections are overridden by any fields explicitly named in fields

  • fields mapping (optional) include or exclude fields from the output. These selections override the settings in defaultFields

    • key Desired output field (see the "Outputs" section below for valid values)

    • value boolean Whether to include the field

The following options are deprecated (and will not be respected if fields is present):

  • appsInstalled boolean (optional, default false) Whether to return the list of apps the user has installed

  • orgs boolean (optional, default false) Whether to return the list of all organizations of which the user is a member

  • pendingTransfers boolean (optional, default false) If true, returns a list of project IDs which the user has been invited to be the billing account for

Outputs

  • id string ID of the user (i.e. the string "user-xxxx")

The following fields are included by default (but can be disabled using$ fields or defaultFields):

  • class string The value "user"

  • first string The user's first name

  • last string The user's last name

  • middle string The user's middle initial or name (may be the empty string)

  • handle string The user's username (handle)

The rest of the keys are only present if the requesting user is the same as the user being described AND a full scope token is supplied.

The following fields are included by default (but can be disabled using fields or defaultFields):

  • createdBy mapping Contains information on how the account was created

    • user string The user who created the account; this is the same as id if the user signed up for an account themselves

    • org string (present if applicable) The organization ID on behalf of which the user indicated in createdBy.user created this user account

  • email string The user's e-mail address

  • billTo string The default value of billTo that will be used for all new projects created by this user

  • securityLevel string The user's security level, either "high" or "normal"

  • otpEnabled boolean Whether one time password-based multi-factor authentication is enabled on the user's account.

  • passwordExpiresAt timestamp (present if securityLevel is "high") Time at which the user's password will expire

  • phiFeaturesEnabled boolean Whether the user has protected health information (PHI) features enabled. Projects using PHI will be subject to additional restrictions to ensure security and compliance

  • sso boolean (optional, default undefined, treated as false) Present and set to true only if the user is an SSO (single sign-on) user.

  • samlIdentityProvider string (optional, present if sso is true) entityID of the SAML 2.0 identity provider used by this user.

  • pendingBillingInformation mapping or null A mapping containing billing information that will go into effect once the accounts payable contact agrees to and confirms the billing information, or null if there is no pending billing information

  • estSpendingLimitLeft number or null Estimated number of dollars left before new activities billed to the user are locked down; the value null indicates that there is no spending limit currently imposed on the account. Note that this value may also be negative to indicate that the user has exceeded the spending limit (it may continue to become more negative if jobs are still running or any projects with a nonzero amount of storage are still billed to the user).

  • computeCharges number Running total of compute charges (in dollars) for the account

  • storageCharges number Running total of storage charges (in dollars) for the account

  • storageChargesComputedAt timestamp Effective time at which storageCharges was computed

  • dataEgressCharges number Running total of data egress charges (in dollars) for the account

If billing information has been confirmed for this billing account:

  • billingInformation mapping The confirmed contact information to which invoices will be sent

The following fields are only returned if the corresponding field in fields is set to true and billing information has been confirmed for this account:

  • pricingModelsByRegion mapping Contains information about the pricing models that are in effect for the user (applied to projects whose billTo is this user). The mapping has one entry for each region in the permittedRegions of the user:

    • key region, e.g. "aws:us-east-1"

    • value mapping the pricing model that is applied in this region

      • storageRatePerGBMonth number Storage rate (in dollars per GB-month) for ordinary (non-archival) storage in this region

        • key Instance type name

        • value number Rate (in dollars per instance-hour)

      • ipRates mapping Rate for data leaving DNAnexus from this region to specific destination IP ranges (specified in CIDR notation). If an IP is in more than one specified range, the rate is given by the most specific matching IP range. The key "0.0.0.0/0" will always exist and contain the default rate

        • key IP range (specified in CIDR notation)

        • value number Rate (in dollars per GB) leaving DNAnexus to that IP range

        The following field will be present only if the user has the phiFeaturesEnabled field set to true:

      • computeRatesPerHourPHI mapping Contains compute rates for each instance type the account is permitted to use in this region, applied only to projects that have the containsPHI flag set

        • key Instance type name

        • value number Rate (in dollars per instance-hour) for this instance type

The following fields are only returned if the corresponding field in fields is set to true:

  • appsInstalled mapping Lists installed apps

    • key App name

    • value boolean The value true

  • orgs array of strings List of IDs of organizations of which the user is a member

  • pendingTransfers array of strings List of project IDs which the user has been invited to be the billing account for

Errors

  • ResourceNotFound (the specified user does not exist)

  • InvalidInput (the input is not a hash, appsInstalled, orgs or pendingTransfers (if provided) is not a boolean)

API Method: /user-xxxx/update

Specification

Updates information about the specified user. Only the user themself has permission to invoke. The user's first, middle, and last names may be visible to other authenticated DNAnexus users.

Inputs

  • first string The user's first name

  • last string The user's last name

  • middle string The user's middle initial or name (may be the empty string)

  • policies mapping (optional) User preferences to update

    • emailWhenJobComplete string (optional, default policy is "always") Indicates when email notifications are sent for successful and failed executions (e.g. jobs). Valid values:

      • "always": always email the user when an execution completes, whether it fails or succeeds

      • "failuresOnly": only email the user when an execution fails

      • "never": do not email the user about successful or failed executions

  • sshPublicKey string or null an SSH public key that will be used to authenticate the user for the purposes of SSHing into jobs. If the value is null, the public key is unset (removing the user's ability to log in to any subsequently created jobs).

  • billTo string (optional) ID of the default entity to which any costs associated with projects and apps created by the user will be billed; must be the ID of the user or an org in which the user is a member with allowBillableActivities permission

Outputs

  • id string ID of the updated user

Errors

  • ResourceNotFound (the specified user does not exist)

  • InvalidInput

    • The input is not a hash

    • first, last, or middle (if provided) is not a string

    • first or last is an empty string

    • sshPublicKey is not either a string or null

    • the keys and value of policies are invalid

    • defaultRegion is not among a user's permittedRegions

  • PermissionDenied

    • A full scope token belonging to the user that is to be updated is required

    • billTo must be either the ID of the requesting user or the ID of an org in which the requesting user is a member with allowBillableActivities permission

policies mapping User preferences. For a description of each policy, see the the inputs of . Returns all policies, even those that have not been set (and thus are at their default value).

sshPublicKey User's public key for use with SSH (or null if no key has been set via ).

defaultRegion string The default region in which newly created projects billed to this user will reside (may be overriden at project creation time). For more information about regions, see .

permittedRegions array of strings The regions in which this user is permitted to create projects. For more information about regions, see .

computeRatesPerHour mapping Contains compute rates for each instance type the user is permitted to use in this region. For a list of available instance types, see:

defaultRegion string (optional) The default region in which all newly created projects billed to this user will reside (may be overriden at project creation time). For more information about regions, see .

Regions
Regions
Instance Types
Regions
/user-xxxx/update
/user-xxxx/update
Platform signup page
contact DNAnexus Sales
/system/findProjects