Users API

Create a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v1/users

Creates a new User. The username given must be unique to ACTIVATED and LOCKED Users for an Account. Upon creation, both an API_KEY and an ACCESS_TOKEN will be automatically vended to the user. For security reasons, the API_KEY will only be shown upon creation or via the TrueVault Management Console for the account’s administrators. If group_ids is provided, the newly created user will be added to all given groups. The user making the request must have the C Group::GROUPID::GroupMembership::.* or U Group::GROUPID permission for all given groups. Please see authorization for more information regarding recommendations for API_KEY and ACCESS_TOKEN usage.

Request Headers:
 
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - return User attributes and Group IDs
Form Parameters:
 
  • username – string(req’d) - username for the User being created
  • password – string(optional) - password for the User being created. If created without a password, the user can’t authenticate using the login endpoint, but it can still have an API key. This allows creating service accounts for backups or other server-to-TrueVault communication.
  • attributes – b64 string(optional) - base64 encoded JSON document describing the User attributes
  • group_ids – string(optional) - comma separated list of group IDs where the new user will be placed
  • status – string(optional) - the user’s status, one of ACTIVATED (default), PENDING, or LOCKED
  • access_token_not_valid_after – string(optional) - expiration time of generated access token
Status Codes:

Example Request

curl https://api.truevault.com/v1/users \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "username=test_user_0&password=deadbeef&attributes=e30=&not_valid_after=2000-00-00T00:0:00.000Z"

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "access_token": ".eJwljbsOwjAMAP8lK1hyEru",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "api_key": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "status": "ACTIVATED",
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_0",
        "mfa_enrolled": false
    }
}

Read a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v2/users/(string: user_id)

Returns information about one or more users. If any IDs aren’t valid UUIDs, returns a 400. If any can’t be found or the user doesn’t have permission to read them, returns a 404. Otherwise, returns 200.

Parameters:
  • user_id – string(req’d) - comma separated list of user IDs to retrieve. At most 100 ids can be fetched at a time.

Note: When full=true, this endpoint consumes an Operation for every user returned, so a request with 50 ids will count as 50 Operations. When full=false, it consumes 1 operation regardless of how many users are returned

Request Headers:
 
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - return User attributes and Group IDs
Status Codes:

Example Request

curl https://api.truevault.com/v2/users/00000000-0000-0000-0000-000000000000,00000000-0000-0000-0000-000000000000 \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "users": [
        {
            "account_id": "00000000-0000-0000-0000-000000000000",
            "id": "00000000-0000-0000-0000-000000000000",
            "status": "ACTIVATED",
            "user_id": "00000000-0000-0000-0000-000000000000",
            "username": "test_user1",
            "mfa_enrolled": false
        },{
            "account_id": "00000000-0000-0000-0000-000000000000",
            "id": "00000000-0000-0000-0000-000000000000",
            "status": "ACTIVATED",
            "user_id": "00000000-0000-0000-0000-000000000000",
            "username": "test_user2",
            "mfa_enrolled": false
        }
    ]
}
Deprecated version
GET /v1/users/(string: user_id)

Returns information about the User.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - return User attributes and Group IDs
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000 \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "account_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "status": "ACTIVATED",
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user",
        "mfa_enrolled": false
    }
}

List all Users

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v1/users

Returns all Users belonging to an Account.

Query Parameters:
 
  • status – string(optional, default: ‘ACTIVATED’) - comma separated list of statuses (inclusive). Accepts any combination of ACTIVATED, DEACTIVATED, or LOCKED.
  • full – boolean(optional, default: ‘false’) - return User attributes and Group IDs. Note: If true, then this endpoint consumes an Operation for every user returned. If false, only a single Operation is used.
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "users": [
        {
            "account_id": "00000000-0000-0000-0000-000000000000",
            "id": "00000000-0000-0000-0000-000000000000",
            "status": "ACTIVATED",
            "user_id": "00000000-0000-0000-0000-000000000000",
            "username": "test_user_0",
            "mfa_enrolled": false
        },
        {
            "account_id": "00000000-0000-0000-0000-000000000000",
            "id": "00000000-0000-0000-0000-000000000000",
            "status": "ACTIVATED",
            "user_id": "00000000-0000-0000-0000-000000000000",
            "username": "test_user_1",
            "mfa_enrolled": false
        }
    ]
}

Update a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
PUT /v1/users/(string: user_id)

Updates a given User’s properties. Strictly overwrites existing values.

WARNING

Updating a User from DEACTIVATED to any other status is not possible at this time. Please exercise caution when doing so.

Parameters:
  • user_id – string(req’d)
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - return User attributes and Group IDs
Form Parameters:
 
  • username – string(optional) - new username
  • password – string(optional) - new password
  • access_token – string(optional) - if this param is included with a non-empty value, include a new access token in the response
  • access_token_not_valid_after – string(optional) - expiration time of generated access token
  • attributes – b64 string(optional) - modify the User’s attributes Document
  • status – string(optional) - manually change the status of a user. Accepts LOCKED, ACTIVATED, and DEACTIVATED.
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000 \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "username=test_user_1&access_token=true&password=deadbeef&attributes=e30=&access_token_not_valid_after=2000-00-00T00:0:00.000Z"

Example Response

Because access_token was provided with a non-empty value, a new access token is included in the response.

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "access_token": ".eJwl2jfaAJHFlk8xHsa",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "status": "ACTIVATED",
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_1",
        "mfa_enrolled": false
    }
}

Update a User’s Password

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
PUT /v1/users/(string: user_id)/password

Updates a given User’s password.

Requires the U activity on the User::USERID::Password or User::USERID resource.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/password \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{"password": "s0meN3wPass"}'

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
}

Delete a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png

Warning

This endpoint does not delete any data permanently, unlike the Document and BLOB delete endpoints. If you need to completely purge a user’s data for policy or compliance reasons, first update the user’s attributes to be {}, then update their username to be a unique random string, then call this endpoint.

DELETE /v1/users/(string: user_id)

Deactivates a user: frees the associated username, all ACCESS_TOKENs, and removes user_id from all Groups.

WARNING: Once the user has been deactivated, it cannot be reactivated via a status update.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "account_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "status": "DEACTIVATED",
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_0",
        "mfa_enrolled": false
    }
}

Create Access Token for a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v1/users/(string: user_id)/access_token

Vends a new ACCESS_TOKEN for user_id.

Parameters:
  • user_id – string(req’d)
Form Parameters:
 
  • not_valid_after – string(optional) - expiration time of returned access token
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/access_token \
    -X POST \
    -d "not_valid_after=2000-00-00T00:0:00.000Z" \
    -u [API_KEY]:

Example Response:

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "access_token": ".eJwljcsKwjAQRf8lWx2YJJNp0q24dOe-TN",
        "account_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "status": "ACTIVATED",
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_0",
        "mfa_enrolled": false
    }
}

Create API Key for a User

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v1/users/(string: user_id)/api_key

Replaces the current API_KEY for user_id. Companion to ACCESS_TOKEN method. Must have U group permissions for the user.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/api_key \
    -X POST \
    -u [API_KEY]:

Example Response

{
    "api_key": "00000000-0000-0000-0000-000000000000",
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Create Access Key and Secret Key for a User

Warning

This endpoint has been deprecated along with the corresponding Files endpoints that depend on this functionality.

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v1/users/(string: user_id)/access_key

Replaces the current Access Key and Secret Key for the specified User. Access Key is used by the Files API.

WARNING

Please copy these keys immediately as there is not a way to reveal them again.

If you generate these keys again, be sure to update your application accordingly. Note that these keys are not updated until you call this endpoint again.

These keys are shared secrets between you and TrueVault. They must never be publicized.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

{
    "user": {
        "id": "00000000-0000-0000-0000-000000000000",
        "access_key": "00000000-0000-0000-0000-000000000000",
        "secret_key": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Start MFA Enrollment for a User

https://d33wubrfki0l68.cloudfront.net/bec271c677d82a3cf60d45d2b806d79b1e0ee7f3/f7045/_images/plans-available-advanced-plus.png
POST /v1/users/(string: user_id)/mfa/start_enrollment

Start MFA enrollment for a User.

Generates and returns MFA secret as QR code, MFA URI, and the raw secret text. This can only be called when enrollment is not complete.

We take the provided MFA issuer (issuer), and return it as part of the MFA URI (uri). This URI is what we use to generate the QR code (qr_code_svg). We provide a raw URI as well as a QR code in case you want to generate a QR code yourself.

The returned QR code is SVG image data - to use this directly on a web page, you can include it in an HTML tag: <img src="data:image/svg+xml;base64,{{BASE64ENCODE(qr_code_svg)}}">

Upon scanning the QR code with an MFA application (Google Authenticator, Authy, etc.), an entry with issuer and username is created in the application. We replace any colons in issuer with underscores in the MFA URI we return.

We also return the MFA secret (secret). We recommend that you display this alongside a QR code so that your end users can enter it manually if needed.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
JSON Parameters:
 
  • issuer (string) – MFA issuer

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/mfa/start_enrollment \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "issuer": "Acme Corporation"
    }'

Example Success Response

HTTP Status Code: 200

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user_mfa": {
        "qr_code_svg": "string",
        "secret": "string",
        "uri": "string"
    }
}

Finalize MFA Enrollment for a User

https://d33wubrfki0l68.cloudfront.net/bec271c677d82a3cf60d45d2b806d79b1e0ee7f3/f7045/_images/plans-available-advanced-plus.png
POST /v1/users/(string: user_id)/mfa/finalize_enrollment

Finalize MFA enrollment for a User.

Send two consecutive MFA codes for the User to finalize their MFA enrollment. Once the User’s MFA enrollment is finalized, they must send an MFA code in addition to username and password to the Login a User endpoint.

Note that an MFA code can only be used once. Therefore a User won’t be able to log in with the MFA code they used to finalize enrollment.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
JSON Parameters:
 
  • mfa_code_1 (string) – First MFA code
  • mfa_code_2 (string) – Second MFA code (must be consecutive with the first)

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/mfa/finalize_enrollment \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "mfa_code_1": "123456",
         "mfa_code_2": "789012"
    }'

Example Success Response

HTTP Status Code: 200

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Example Error Response - User MFA Enrollment Failure

HTTP Status Code: 400

{
    "result": "error",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "error": {
        "message": "User MFA enrollment failed",
        "type": "USER.MFA_FINALIZE_ENROLLMENT_FAILURE"
    }
}

Unenroll MFA for a User

https://d33wubrfki0l68.cloudfront.net/bec271c677d82a3cf60d45d2b806d79b1e0ee7f3/f7045/_images/plans-available-advanced-plus.png
POST /v1/users/(string: user_id)/mfa/unenroll

Unenroll a User from MFA.

Send an MFA code and a password for the User to unenroll them from MFA. If successful, the User will no longer need to provide an MFA code when using the Login a User endpoint.

Warning

If a user enters an incorrect password and a correct MFA code, they must wait for another MFA code to try again. It is best practice to reflect this behavior in the messaging you display to your end users. For security reasons, we do not return whether the password or the MFA code was incorrect, so it is best to make the cause ambiguous in your messaging.

Parameters:
  • user_id – string(req’d)
Request Headers:
 
JSON Parameters:
 
  • mfa_code (string) – MFA code for User
  • password (string) – User’s password

Example Request

curl https://api.truevault.com/v1/users/00000000-0000-0000-0000-000000000000/mfa/unenroll \
 -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{
         "mfa_code": "123456",
         "password": "deadbeef"
    }'

Example Success Response

HTTP Status Code: 200

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Example Error Response - User MFA Unenrollment Failure

HTTP Status Code: 400

{
    "result": "error",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "error": {
        "message": "User MFA unenrollment failed",
        "type": "USER.MFA_FINALIZE_UNENROLLMENT_FAILURE"
    }
}