openapi: 3.1.0
info:
  title: Login.gov OpenID Connect 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: Discovery
  description: OIDC discovery and public key endpoints.
- name: Authorization
  description: OAuth 2.0 authorization endpoint where the user authenticates.
- name: Token
  description: Token exchange using private_key_jwt or PKCE.
- name: UserInfo
  description: User attribute retrieval with a bearer access token.
- name: Logout
  description: RP-initiated logout and session termination.
paths:
  /.well-known/openid-configuration:
    get:
      tags:
      - Discovery
      summary: Get OIDC Discovery Document
      operationId: getOpenidConfiguration
      description: Returns the OpenID Connect discovery document listing supported endpoints, scopes, response types, claims, and acr_values.
      responses:
        '200':
          description: Discovery metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryDocument'
  /api/openid_connect/certs:
    get:
      tags:
      - Discovery
      summary: Get JWKS Signing Keys
      operationId: getJwks
      description: Returns Login.gov's public signing key(s) in JWK Set format. Keys are rotated at least annually; clients should fetch dynamically rather than hard-coding.
      responses:
        '200':
          description: JSON Web Key Set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwkSet'
  /openid_connect/authorize:
    get:
      tags:
      - Authorization
      summary: Start Authorization Flow
      operationId: authorize
      description: |
        Begins the OIDC authorization code flow. The user is redirected to Login.gov, authenticates,
        consents to the requested scopes, and is redirected back to `redirect_uri` with an
        authorization `code` and the original `state` value.
      parameters:
      - name: client_id
        in: query
        required: true
        description: Registered relying party identifier.
        schema:
          type: string
      - name: response_type
        in: query
        required: true
        description: Must be `code`. Implicit flow is not supported.
        schema:
          type: string
          enum:
          - code
      - name: scope
        in: query
        required: true
        description: Space-separated list of requested scopes. Must include `openid`.
        schema:
          type: string
          example: openid email profile
      - name: redirect_uri
        in: query
        required: true
        description: Pre-registered redirect URI. Must match exactly.
        schema:
          type: string
          format: uri
      - name: nonce
        in: query
        required: true
        description: Random string (minimum 22 characters) bound to the id_token to prevent replay.
        schema:
          type: string
          minLength: 22
      - name: state
        in: query
        required: true
        description: Opaque value (minimum 22 characters) returned with the callback for CSRF protection and request/callback correlation.
        schema:
          type: string
          minLength: 22
      - name: prompt
        in: query
        required: true
        description: Must be `select_account`.
        schema:
          type: string
          enum:
          - select_account
      - name: acr_values
        in: query
        required: false
        description: Requested authentication context. Combines a service level and an authenticator assurance level.
        schema:
          type: string
          example: urn:acr.login.gov:auth-only http://idmanagement.gov/ns/assurance/aal/2
      - name: locale
        in: query
        required: false
        description: Override the user's locale.
        schema:
          type: string
          enum:
          - ES
          - FR
      - name: code_challenge
        in: query
        required: false
        description: PKCE code challenge (base64url SHA-256 of `code_verifier`). Required for native apps using PKCE instead of private_key_jwt.
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: false
        description: PKCE method. Login.gov supports `S256`.
        schema:
          type: string
          enum:
          - S256
      responses:
        '302':
          description: Redirect to Login.gov for authentication, then back to `redirect_uri` with `code` and `state`.
  /api/openid_connect/token:
    post:
      tags:
      - Token
      summary: Exchange Authorization Code for Tokens
      operationId: exchangeToken
      description: |
        Exchanges the authorization code for an `access_token` and a signed `id_token`. Web apps
        authenticate using `private_key_jwt`; native apps use PKCE with a `code_verifier`.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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'
  /openid_connect/logout:
    get:
      tags:
      - Logout
      summary: RP-Initiated Logout
      operationId: logout
      description: |
        Ends the user's Login.gov session. After confirmation the browser is redirected to the
        pre-registered `post_logout_redirect_uri` with the original `state` value.
      parameters:
      - name: client_id
        in: query
        required: true
        description: Registered relying party identifier.
        schema:
          type: string
      - name: post_logout_redirect_uri
        in: query
        required: true
        description: Pre-registered post-logout redirect URI.
        schema:
          type: string
          format: uri
      - name: state
        in: query
        required: false
        description: Opaque value (minimum 22 characters) echoed back to `post_logout_redirect_uri`.
        schema:
          type: string
          minLength: 22
      responses:
        '302':
          description: Redirect back to `post_logout_redirect_uri` after the user confirms logout.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
  schemas:
    DiscoveryDocument:
      type: object
      properties:
        issuer:
          type: string
          example: https://idp.int.identitysandbox.gov
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        userinfo_endpoint:
          type: string
          format: uri
        end_session_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        acr_values_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
        subject_types_supported:
          type: array
          items:
            type: string
        claims_supported:
          type: array
          items:
            type: string
    JwkSet:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Jwk'
    Jwk:
      type: object
      properties:
        kty:
          type: string
          example: RSA
        kid:
          type: string
        use:
          type: string
          example: sig
        alg:
          type: string
          example: RS256
        'n':
          type: string
        e:
          type: string
    TokenRequest:
      type: object
      required:
      - grant_type
      - code
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
        code:
          type: string
          description: Authorization code returned from `/openid_connect/authorize`.
        client_assertion_type:
          type: string
          description: Required for private_key_jwt clients.
          enum:
          - urn:ietf:params:oauth:client-assertion-type:jwt-bearer
        client_assertion:
          type: string
          description: Signed JWT (RS256) where `iss` and `sub` are `client_id`, `aud` is the token endpoint, and `jti`, `iat`, `exp` are set. Minimum 2048-bit key.
        code_verifier:
          type: string
          description: PKCE code verifier matching the original `code_challenge`. Used by native apps in lieu of `client_assertion`.
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Opaque bearer token for the userinfo endpoint.
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Lifetime of the access token in seconds.
        id_token:
          type: string
          description: Signed JWT (RS256) carrying authenticated user identity claims.
    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
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string