Login.gov SAML 2.0 API

SAML 2.0 federation surface for relying parties that prefer SAML over OIDC. Uses HTTP-Redirect SSO and HTTP-POST SLO with the persistent NameID format (UUID v4). Endpoints are year-versioned (2026 = certificates valid through April 1, 2027). Metadata is published; clients should consume it dynamically to handle annual certificate rotations.

Login.gov SAML 2.0 API is one of 2 APIs that Login.gov publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include SAML, Authentication, SSO, and Federal. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.1.0
info:
  title: Login.gov SAML 2.0 API
  version: '2026-01'
  description: |
    Login.gov also supports SAML 2.0 for relying parties that prefer enterprise federation
    semantics over OIDC. SAML endpoints are versioned by certificate year (the `2026` suffix
    corresponds to certificates valid through April 1, 2027). The persistent NameID format
    issues a per-RP UUID v4.

    The SSO endpoint accepts the HTTP-Redirect binding; SLO uses HTTP-POST. Login.gov's
    SAML certificates are published in the metadata endpoint and should be loaded
    dynamically so that annual rotations do not require code changes.
  contact:
    name: Login.gov Partner Support
    url: https://developers.login.gov
    email: [email protected]
  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: Metadata
  description: SAML 2.0 IdP metadata.
- name: Authentication
  description: SAML SSO request endpoint.
- name: Logout
  description: SAML Single Logout endpoint.
paths:
  /api/saml/metadata2026:
    get:
      tags:
      - Metadata
      summary: Get SAML 2.0 IdP Metadata
      operationId: getSamlMetadata
      description: Returns the SAML 2.0 IdP metadata XML including entity ID, SSO/SLO endpoints, signing certificate, and supported NameID formats.
      responses:
        '200':
          description: SAML metadata document.
          content:
            application/samlmetadata+xml:
              schema:
                type: string
                format: xml
            application/xml:
              schema:
                type: string
                format: xml
  /api/saml/auth2026:
    get:
      tags:
      - Authentication
      summary: Initiate SAML SSO (HTTP-Redirect)
      operationId: samlSso
      description: |
        Accepts a Base64-encoded, DEFLATE-compressed `SAMLRequest` via HTTP-Redirect.
        The user authenticates with Login.gov and the IdP responds with a signed SAML
        assertion POSTed to the SP's Assertion Consumer Service URL.
      parameters:
      - name: SAMLRequest
        in: query
        required: true
        description: Base64-encoded DEFLATE-compressed AuthnRequest.
        schema:
          type: string
      - name: RelayState
        in: query
        required: false
        description: Opaque value echoed back in the SAML response.
        schema:
          type: string
      - name: SigAlg
        in: query
        required: false
        description: Signature algorithm URI when the request is signed.
        schema:
          type: string
      - name: Signature
        in: query
        required: false
        description: Base64-encoded signature over the request.
        schema:
          type: string
      responses:
        '200':
          description: Login.gov sign-in UI is rendered to the end user.
        '302':
          description: Redirect to authentication challenge or to SP ACS with the signed SAML response.
  /api/saml/logout2026:
    post:
      tags:
      - Logout
      summary: SAML Single Logout (HTTP-POST)
      operationId: samlSlo
      description: Accepts a signed `LogoutRequest` from the SP and terminates the user's Login.gov session.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - SAMLRequest
              properties:
                SAMLRequest:
                  type: string
                  description: Base64-encoded SAML LogoutRequest.
                RelayState:
                  type: string
      responses:
        '200':
          description: LogoutResponse posted back to the SP's SLO endpoint.
components:
  schemas:
    SamlAssertionAttributes:
      type: object
      description: Attributes returned in a Login.gov SAML assertion (attribute names follow Login.gov conventions, not OIDC claim names).
      properties:
        uuid:
          type: string
          description: Stable per-RP user identifier.
        email:
          type: string
        all_emails:
          type: string
        locale:
          type: string
        ial:
          type: string
        aal:
          type: string
        first_name:
          type: string
          description: Available at IAL2.
        last_name:
          type: string
          description: Available at IAL2.
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        phone:
          type: string
        dob:
          type: string
          format: date
        ssn:
          type: string
          description: Social Security Number. Available at IAL2 only.
        verified_at:
          type: string
        x509_subject:
          type: string
        x509_issuer:
          type: string
        x509_presented:
          type: string

Login.gov SAML 2.0 API

Documentation

Specifications

Other Resources

OpenAPI Specification