Authentication

Authenticated requests to vets-api provide access to a User object containing information about the user who made the request. Your integration may utilize this object to pass Veteran information to your service for authentication or processing purposes. By default, all controller actions are non-public facing and require authentication.

From any controller, the User object can be obtained with the current_user method:

CODE

module MyService
  class ExamplesController < ApplicationController
    def index
      # The @user variable is assigned the currently authenticated User object
      @user = current_user
      render json: { status: 'ok' }
    end
  end
end

Levels of Assurance

Vets-api provides guarantees that the user initiating the request is correlated to the identifying information within the User object.

Identity Assurance Level (IAL)

Note: Starting September 30, 2025 new VA.gov users creating an account with Login.gov or ID.me will follow the updated NIST guidelines for digital identity.

The revised guidelines from NIST separate the definitions of identity assurance levels from authenticator assurance levels.

Identity Assurance Level 2 (IAL2): IAL2 requires collecting additional evidence and a more rigorous process for validating the evidence and verifying the identity. New users require IAL2 identity proofing. After someone submits a photo of their identity documents, they’ll take a live selfie to confirm that the person submitting the ID is really them. This process is required for users to access sensitive personal and financial information on VA.gov.
Identity Assurance Level 1 (IAL1): IAL1 supports the real-world existence of the claimed identity and provides some assurance that the applicant is associated with that identity. Core attributes are obtained from identity evidence or self-asserted by the applicant. All core attributes are validated against authoritative or credible sources, and steps are taken to link the attributes to the person undergoing the identity proofing process. This process is supported for limited actions on VA.gov, such as completing a form.

Authenticator Assurance Level (AAL)

Authenticator Assurance Level 2 (AAL2): All users sign in on VA.gov with multi-factor authentication (MFA).

Legacy Levels of Assurance (LOA)

Note: These guidelines apply to VA.gov accounts created before September 30, 2025.

There are four possible Levels of Assurance provided based on the mechanism by which the user authenticated. Ensure you are familiar with each of them, and validate the proper LOA requirements appropriately in your integration's policies. Documentation on Authorization provides details on how to provide services only to users authenticated with the proper LOA.

Level 1: There is no identity proofing requirement at this level. However, the fact that the user is able to authenticate to the identity provider gives some assurance. It means the identity provider has some relationship with the user because they have issued them a credential (username and password). Credentials are required to login.

Level 2: In addition to level 1, identity proofing requirements are introduced, requiring presentation of identifying materials or information. Credentials are required to login. VA.gov does not support this level of assurance currently.

Level 3: In addition to level 2, identity proofing procedures require verification of identifying materials and information. Both in-person and remote registration are permitted. Level 3 requires the same evidence for issuing credentials as Level 2; however at this level verification of the documents or references through record checks is required. ID.me facilitates this through an industry recognized standard known as FICAM. Credentials are required to sign in.

Level 4: Vets.gov does not support this level of assurance currently.

Overriding Authentication

Authentication is required by default for all requests to Vets-API. To bypass authentication and provide a public endpoint, you can skip the authentication process.

CODE

# config/routes.rb
...
namespace :v0, defaults: { format: 'json' }
  ...
  namespace :my_service do
    resources :examples, only: [:public]
  end
  ...
end
...

# app/controllers/my_service/example_controller.rb
module MyService
  class ExamplesController < ApplicationController
    skip_before_action :authenticate

    # This endpoint is publicly available
    def public
      render json: { status: 'world readable' }
    end
  end
end

Session Timeout

Sessions expire after 15 minutes of inactivity. Sessions reset with API calls to vets-api, for a maximum of 12 hours. 30 seconds before the session ends, a modal prompts the user to click a button to continue their session, otherwise they're signed out.

Profile Data Sources

The User object is serialized out to JSON as user profile data. The data is derived from a number of different sources including but not limited to the following:

The SAML Response returned from the identity provider. (ID.me)
- See UserIdentity: only attributes coming from the IDP should ever be stored on UserIdentity
The Master Person Index (MPI)
- See mvi/service: This data is fetched once per day and is cached in Redis. (Note: MPI was previously named “Master Veteran Index (MVI.)

Rules of precedence are available in the User object.

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.