Login.gov UserInfo API

openapi: 3.1.0
info:
  title: Login.gov OpenID Connect Authentication UserInfo API
  version: 2026-01
  description: 'Login.gov is the U.S. federal government''s secure single sign-on service for public-facing

    government applications, operated by the General Services Administration''s Technology

    Transformation Services. This OpenAPI describes the OpenID Connect (OIDC) integration

    surface used by relying parties (service providers) to authenticate users at IAL1 (auth

    only) and IAL2 (identity-verified) assurance levels.


    Login.gov conforms to the iGov OpenID Connect Profile. Implicit flow is not supported.

    Client authentication uses private_key_jwt (preferred for web apps) or PKCE

    (preferred for native mobile apps).

    '
  contact:
    name: Login.gov Partner Support
    url: https://developers.login.gov
    email: partners@login.gov
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
servers:
- url: https://idp.int.identitysandbox.gov
  description: Sandbox (integration) environment
- url: https://secure.login.gov
  description: Production environment
tags:
- name: UserInfo
  description: User attribute retrieval with a bearer access token.
paths:
  /api/openid_connect/userinfo:
    get:
      tags:
      - UserInfo
      summary: Get Authenticated User Attributes
      operationId: getUserInfo
      description: Returns user attributes consented to during authorization. Requires a bearer `access_token`.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
    UserInfo:
      type: object
      properties:
        sub:
          type: string
          description: Stable per-RP user UUID v4.
        iss:
          type: string
          format: uri
        email:
          type: string
          format: email
        email_verified:
          type: boolean
        all_emails:
          type: array
          items:
            type: string
            format: email
        locale:
          type: string
        ial:
          type: string
          description: Identity assurance level granted (e.g. `http://idmanagement.gov/ns/assurance/ial/1`).
        aal:
          type: string
          description: Authenticator assurance level granted.
        given_name:
          type: string
          description: Available at IAL2.
        family_name:
          type: string
          description: Available at IAL2.
        address:
          $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: E.164 phone number. Available at IAL2.
        phone_verified:
          type: boolean
        birthdate:
          type: string
          format: date
          description: Available at IAL2.
        social_security_number:
          type: string
          description: Available at IAL2 with the `social_security_number` scope; SSN may be unmasked or last-4 depending on configuration.
        verified_at:
          type: integer
          description: Unix timestamp when the user's identity was verified. Null if never verified.
        x509_subject:
          type: string
        x509_issuer:
          type: string
        x509_presented:
          type: boolean
    Address:
      type: object
      properties:
        formatted:
          type: string
        street_address:
          type: string
        locality:
          type: string
        region:
          type: string
        postal_code:
          type: string
        country:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque