# Users

Users can create their own DNAnexus user accounts by registering via the [Platform signup page](https://platform.dnanexus.com/register). For orgs covered by a license that enables account provisioning, org admins can create accounts for other users on behalf of the org.

{% hint style="info" %}
For more information on a license that enables account provisioning by org admins, [contact DNAnexus Sales](mailto:sales@dnanexus.com).
{% endhint %}

The Platform provides 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 turn this username into a user object ID, the username is transformed to lowercase, 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. 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 [`/system/findProjects`](https://documentation.dnanexus.com/developer/system-methods#api-method-system-findprojects).

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) 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`.
  * Defaults to `false` if `fields` is supplied, `true` otherwise.
* `fields` **mapping** (optional) Include or exclude fields from the output. These selections override the settings in `defaultFields`.
  * **key** — the desired output field. See "Outputs" below for valid values.
  * **value** **boolean** — whether to include the field.

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

* `appsInstalled` **boolean** (optional, deprecated) Whether to return the list of apps the user has installed. Defaults to `false`.
* `orgs` **boolean** (optional, deprecated) Whether to return the list of all organizations of which the user is a member. Defaults to `false`.
* `pendingTransfers` **boolean** (optional, deprecated) If `true`, returns a list of project IDs which the user has been invited to be the billing account for. Defaults to `false`.

### Outputs

* `id` **string** ID of the user in the format "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** The organization ID on behalf of which the user indicated in `createdBy.user` created this user account.
    * Only present when applicable.
* `email` **string** The user's e-mail address.
* `billTo` **string** The default value of `billTo` that is used for all new projects created by this user.
* `securityLevel` **string** The user's security level.
  * Must be one of `"high"` or `"normal"`.
* `otpEnabled` **boolean** Whether one time password-based multi-factor authentication is enabled on the user's account.
* `passwordExpiresAt` [**timestamp**](https://documentation.dnanexus.com/developer/api/..#data-types) Time at which the user's password expires.
  * Only present when `securityLevel` is `high`.
* `phiFeaturesEnabled` **boolean** Whether the user has protected health information (PHI) features enabled. Projects using PHI are subject to additional restrictions to ensure security and compliance.
* `policies` **mapping** User preferences. For a description of each policy, see the inputs of [`/user-xxxx/update`](#api-method-user-xxxx-update). Returns all policies, even those that have not been set (and are at their default value).
* `sshPublicKey` **string** (nullable) User's public key for use with SSH, or `null` if no key has been set via `/user-xxxx/update`.
* `sso` **boolean** Whether the user is an SSO (single sign-on) user.
  * Only present when set to `true`.
* `samlIdentityProvider` **string** The entityID of the SAML 2.0 identity provider used by this user.
  * Only present when `sso` is `true`.
* `pendingBillingInformation` **mapping** (nullable) A mapping containing billing information that goes 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** (nullable) 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 imposed on the account. This value may also be negative to indicate that the user has exceeded the spending limit.
* `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**](https://documentation.dnanexus.com/developer/api/..#data-types) Effective time at which `storageCharges` was computed.
* `dataEgressCharges` **number** Running total of data egress charges (in dollars) for the account.
* `defaultRegion` **string** The default region in which newly created projects billed to this user reside (may be overridden at project creation time). For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).
* `permittedRegions` **array of strings** The regions in which this user is permitted to create projects. For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).

If billing information has been confirmed for this billing account:

* `billingInformation` **mapping** The confirmed contact information to which invoices are 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** — the region (for example, `aws:us-east-1`).
  * **value** **mapping** — the pricing model applied in this region:
    * `storageRatePerGBMonth` **number** Storage rate (in dollars per GB-month) for ordinary (non-archival) storage in this region.
    * `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 [Instance Types](https://documentation.dnanexus.com/developer/api/running-analyses/instance-types).
      * **key** — the instance type name.
      * **value** **number** — the 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](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)). If an IP is in more than one specified range, the rate is given by the most specific matching IP range. The mapping includes the predefined key "0.0.0.0/0" with the default rate.
      * **key** — the IP range (specified in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)).
      * **value** **number** — the rate (in dollars per GB) leaving DNAnexus to that IP range.

The following field is 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. This field applies only to projects that have the `containsPHI` flag set to `true`.
  * **key** — the instance type name.
  * **value** **number** — the 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** — the 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 themselves has permission to invoke. The user's first, middle, and last names may be visible to other authenticated DNAnexus users.

### Inputs

* `first` **string** (optional) The user's first name.
* `last` **string** (optional) The user's last name.
* `middle` **string** (optional) The user's middle initial or name (may be the empty string).
* `policies` **mapping** (optional) User preferences to update.
  * `emailWhenJobComplete` **string** (optional) Indicates when email notifications are sent for successful and failed executions. Defaults to `"always"`.
    * Must be one of `"always"`, `"failuresOnly"`, or `"never"`.
* `sshPublicKey` **string** (optional, nullable) An SSH public key that is used to authenticate the user for accessing jobs via SSH. If the value is `null`, the public key is unset.
* `billTo` **string** (optional) ID of the default entity to which any costs associated with projects and apps created by the user are billed. It must be the ID of the user or an org in which the user is a member with `allowBillableActivities` permission.
* `defaultRegion` **string** (optional) The default region in which all newly created projects billed to this user reside (may be overridden at project creation time). For more information about regions, see [Regions](https://documentation.dnanexus.com/developer/api/regions).

### 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