Users API¶

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.

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

Vends a new ACCESS_TOKEN for user_id.

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

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

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"
}

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.

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.

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.

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.

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.

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

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"
    }
}