Users
Learn about creating and managing users via the DNAnexus Platform API.
Last updated
Was this helpful?
Learn about creating and managing users via the DNAnexus Platform API.
Last updated
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.
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.
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.
/user-xxxx/describe
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.
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
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
ResourceNotFound (the specified user does not exist)
InvalidInput (the input is not a hash, appsInstalled
, orgs
or pendingTransfers
(if provided) is not a boolean)
/user-xxxx/update
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.
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
id
string ID of the updated user
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 .