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

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
  • account_id – string(req’d) - account_id
Status Codes:

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"

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

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

Logs a User out, deactivating the associated ACCESS_TOKEN.

Request Headers:
 
Status Codes:

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

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

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

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

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

Update current user’s attributes

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

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