Authentication API¶

These endpoints relate to Authentication. If you’re looking for Authorization, see the Groups API. If you are looking for more information on how to authenticate your API requests, see the Authentication Overview.

Login a User¶

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

POST /v1/auth/login¶

Logs a User in using their username, password, and account_id of the provider. Generates an ACCESS_TOKEN.

If MFA is enabled for the user, the will also need to provide a valid mfa_code from their MFA application (Google Authenticator, Authy, etc.).

If not_valid_after is supplied, the returned access token will expire at the given time. The expiration time can be any value, as long as it’s in the future. TrueVault Advanced Security accounts can configure a maximum access token duration in the console. If ommitted, the generated access token will be valid for 24 hours.

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.

Form Parameters:
	username – string(req’d) - `username` of active user password – string(req’d) - `password` of active user mfa_code – string(optional) - `mfa_code` of active user not_valid_after – string(optional) - expiration time of returned access token account_id – string(req’d) - `account_id`
Status Codes:	200 OK – success

Example Request

curl https://api.truevault.com/v1/auth/login \
    -X POST \
    -d "username=test_user_1&password=deadbeef&account_id=00000000-0000-0000-0000-000000000000&not_valid_after=2000-00-00T00:0:00.000Z"

Example Response

{
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000",
    "user": {
        "access_token": ".eJwljbEKwjAaSF93Fdsx",
        "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
    }
}

Logout a User¶

POST /v1/auth/logout¶

Logs a User out, deactivating the associated ACCESS_TOKEN.

Request Headers:
	Authorization – `ACCESS_TOKEN`
Status Codes:	200 OK – success 401 Unauthorized – logout failure

Example Request

curl https://api.truevault.com/v1/auth/logout \
    -X POST \
    -u [ACCESS_TOKEN]:

Example Response

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

Verify a User¶

GET /v1/auth/me¶

Verify provided ACCESS_TOKEN or API_KEY by returning the User’s information.

Request Headers:
	Authorization – `ACCESS_TOKEN` or `API_KEY`
Query Parameters:
	full – boolean(optional, default: ‘false’) - return User attributes and Group IDs
Status Codes:	200 OK – success 400 Bad Request – invalid authorization

Example Request

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

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": 1,
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_0",
        "mfa_enrolled": false
    }
}

Update a User’s attributes¶

PUT /v1/auth/me¶

Update current user’s attributes

Request Headers:
	Authorization – `ACCESS_TOKEN` or `API_KEY`
Query Parameters:
	full – boolean(optional, default: ‘false’) - return User attributes and Group IDs in the response
Status Codes:	200 OK – success 400 Bad Request – invalid authorization

Example Request

curl https://api.truevault.com/v1/auth/me \
    -X PUT \
    -d 'attributes=e30=' \
    -u [ACCESS_TOKEN | API_KEY]:

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": 1,
        "user_id": "00000000-0000-0000-0000-000000000000",
        "username": "test_user_0",
        "mfa_enrolled": false
    }
}