openapi: 3.0.3
info:
  title: CMS Blue Button 2.0 Coverage UserInfo API
  description: Blue Button 2.0 is the Centers for Medicare & Medicaid Services (CMS) patient-facing API that lets Medicare beneficiaries share their Parts A, B, and D claims data with applications they authorize. The v2 API is FHIR R4 (4.0.1) and conforms to the CARIN Blue Button Implementation Guide (CARIN Consumer Directed Payer Data Exchange, CDPDE). It exposes three FHIR resource types - ExplanationOfBenefit (claims), Patient (demographics), and Coverage (Part A/B/D enrollment) - plus a capability statement and an OpenID Connect userinfo endpoint. Every request is scoped to the single beneficiary who authorized the application through the OAuth 2.0 authorization-code flow (PKCE S256 required) on Medicare.gov. The sandbox at sandbox.bluebutton.cms.gov mirrors production with synthetic data for 10,000 enrollees.
  version: '2.0'
  contact:
    name: CMS Blue Button 2.0
    url: https://bluebutton.cms.gov
  termsOfService: https://bluebutton.cms.gov/terms/
servers:
- url: https://api.bluebutton.cms.gov/v2/fhir
  description: Production (approved applications only)
- url: https://sandbox.bluebutton.cms.gov/v2/fhir
  description: Sandbox (synthetic Medicare enrollee data, self-serve)
security:
- oauth2:
  - patient/ExplanationOfBenefit.read
  - patient/Patient.read
  - patient/Coverage.read
tags:
- name: UserInfo
  description: OpenID Connect userinfo for the authorizing beneficiary.
paths:
  /connect/userinfo:
    servers:
    - url: https://api.bluebutton.cms.gov/v2
      description: Production (userinfo lives outside the /fhir base path)
    - url: https://sandbox.bluebutton.cms.gov/v2
      description: Sandbox
    get:
      operationId: getUserInfo
      tags:
      - UserInfo
      summary: Retrieve the authorizing user's OpenID Connect profile
      description: Full path is /v2/connect/userinfo (outside the /fhir base). Returns the authorizing beneficiary's user profile (name, family name, email) when the openid and profile scopes were granted.
      responses:
        '200':
          description: OpenID Connect userinfo JSON.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sub:
                    type: string
                  name:
                    type: string
                  given_name:
                    type: string
                  family_name:
                    type: string
                  email:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing, expired, or invalid OAuth 2.0 access token.
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization-code flow with mandatory PKCE (S256 only). Beneficiaries log in with their Medicare.gov credentials and choose whether to share demographic data. Access tokens expire after 1 hour. One-time-use refresh tokens are issued only to approved 13-month and research application types. Sandbox uses https://sandbox.bluebutton.cms.gov/v2/o/authorize/ and https://sandbox.bluebutton.cms.gov/v2/o/token/.
      flows:
        authorizationCode:
          authorizationUrl: https://api.bluebutton.cms.gov/v2/o/authorize/
          tokenUrl: https://api.bluebutton.cms.gov/v2/o/token/
          refreshUrl: https://api.bluebutton.cms.gov/v2/o/token/
          scopes:
            patient/Patient.read: Read the beneficiary's Patient demographic resource.
            patient/ExplanationOfBenefit.read: Read the beneficiary's Medicare claims.
            patient/Coverage.read: Read the beneficiary's Medicare coverage.
            openid: OpenID Connect authentication.
            profile: Access the userinfo profile endpoint.
            launch/patient: Receive the patient FHIR id in the token response.