Broad Institute Profile API

openapi: 3.2.0
info:
  title: Terra Profile API
  description: Terra API
  termsOfService: https://app.terra.bio/#terms-of-service
  license:
    name: BSD
    url: http://opensource.org/licenses/BSD-3-Clause
  version: '0.1'
servers:
- url: /
security:
- oidc: []
tags:
- name: Profile
paths:
  /api/profile/billingAccounts:
    get:
      tags:
      - Profile
      summary: List billing accounts for a user
      operationId: billingAccounts
      parameters:
      - name: firecloudHasAccess
        in: query
        description: 'Whether the Firecloud service has been given access to the billing accounts. Optional.

          '
        required: false
        example: true
        schema:
          type: boolean
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingAccount'
        403:
          description: Forbidden - redirect to Google to enable appropriate scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAccountRedirect'
        500:
          description: Internal Server Error
          content: {}
      security:
      - oidc_google_billing_scope: []
      x-passthrough: true
      x-passthrough-target: rawls
  /api/profile/importstatus:
    get:
      tags:
      - Profile
      summary: Check the user's ability to import a method config into a workspace
      operationId: importStatus
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserImportPermission'
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
  /api/profile/preferences:
    post:
      tags:
      - Profile
      summary: Update the preferences for the user
      operationId: updateProfile
      requestBody:
        description: The preferences to set as a Map[String, String]
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
        required: true
      responses:
        204:
          description: Success (No Content)
          content: {}
        400:
          description: Bad Request
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: preferences
  /api/profile/terra:
    get:
      tags:
      - Profile
      summary: Returns the current user's preference for Terra UI vs. Legacy view
      operationId: getTerraPreference
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerraPreference'
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
    post:
      tags:
      - Profile
      summary: Sets the current user's preference to use Terra UI, not Legacy view
      operationId: setTerraPreference
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerraPreference'
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
    delete:
      tags:
      - Profile
      summary: Sets the current user's preference to use Legacy view, not Terra UI
      operationId: setFCPreference
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerraPreference'
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
  /me:
    get:
      tags:
      - Profile
      summary: Returns registration and activation status for the current user
      operationId: me
      parameters:
      - name: userDetailsOnly
        in: query
        description: when set to true does not check the various enabled statuses of the user
        schema:
          type: boolean
          default: false
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        401:
          description: Unauthorized. User is not allowed in Terra or has not signed in.
          content: {}
        403:
          description: Forbidden. User is registered in Terra, but not activated.
          content: {}
        404:
          description: Not Found. User is authenticated to Google but not a Terra member.
          content: {}
        500:
          description: Internal Server Error determining user status.
          content: {}
        503:
          description: Service Unavailable. Could not reach underlying services to determine user status.
          content: {}
      x-passthrough: false
  /api/proxyGroup/{email}:
    get:
      tags:
      - Profile
      summary: Returns the proxy group email for the current user
      operationId: getProxyGroup
      parameters:
      - name: email
        in: path
        description: User email whose proxy group to retrieve
        required: true
        schema:
          type: string
      responses:
        200:
          description: user proxy group
          content:
            application/json:
              schema:
                type: string
        404:
          description: user not found
          content: {}
        500:
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorReport'
      x-passthrough: true
      x-passthrough-target: sam
  /register:
    get:
      tags:
      - Profile
      summary: Passes through to the Sam userinfo API and returns its response
      operationId: getUserStatus
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RawlsMe'
        404:
          description: User Not Found.
          content: {}
        500:
          description: Internal Server Error determining Rawls user status.
          content: {}
      x-passthrough: true
      x-passthrough-target: sam
  /register/profile:
    get:
      tags:
      - Profile
      summary: Returns a list of all keys and values stored in the user profile service for…
      operationId: getAll
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterProfile'
            text/plain:
              schema:
                $ref: '#/components/schemas/RegisterProfile'
        500:
          description: Internal server error
          content: {}
      x-passthrough: false
    post:
      tags:
      - Profile
      summary: Sets a profile object in the user profile service for the currently logged-in…
      operationId: setProfile
      requestBody:
        description: A complete profile
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Profile'
        required: false
      responses:
        200:
          description: OK
          content: {}
        400:
          description: Bad request
          content: {}
        403:
          description: Forbidden
          content: {}
        500:
          description: Internal server error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: profile
components:
  schemas:
    ExtendedEnabled:
      allOf:
      - $ref: '#/components/schemas/Enabled'
    ErrorReport:
      required:
      - causes
      - message
      - source
      - stackTrace
      type: object
      properties:
        source:
          type: string
          description: service causing error
        message:
          type: string
          description: what went wrong
        statusCode:
          type: integer
          description: HTTP status code
          format: int32
        causes:
          type: array
          description: errors triggering this one
          items:
            $ref: '#/components/schemas/ErrorReport'
        stackTrace:
          type: array
          description: stack trace
          items:
            $ref: '#/components/schemas/StackTraceElement'
      description: ''
    UserImportPermission:
      type: object
      properties:
        billingProject:
          type: boolean
          description: does the user have at least one ready billing project?
        writableWorkspace:
          type: boolean
          description: does the user have at least one writable workspace?
    UserInfo:
      type: object
      properties:
        userSubjectId:
          type: string
          description: User's ID (subject id from Google)
        userEmail:
          type: string
          description: User's email
    RawlsMe:
      type: object
      properties:
        userInfo:
          $ref: '#/components/schemas/UserInfo'
        enabled:
          $ref: '#/components/schemas/ExtendedEnabled'
    Enabled:
      type: object
      properties:
        google:
          type: boolean
          description: User enabled via Google?
        ldap:
          type: boolean
          description: User enabled in LDAP?
        allUsersGroup:
          type: boolean
          description: User is a member of the "All Users" group?
        adminEnabled:
          type: boolean
          description: User is enabled in the system?
        tosAccepted:
          type: boolean
          description: User has accepted the latest Terms of Service?
    Me:
      type: object
      properties:
        userInfo:
          $ref: '#/components/schemas/UserInfo'
        enabled:
          $ref: '#/components/schemas/Enabled'
    TerraPreference:
      type: object
      properties:
        preferTerra:
          type: boolean
          description: When true, prefer Terra UI; when false, prefer Legacy FireCloud UI.
        preferTerraLastUpdated:
          type: integer
          description: Epoch timestamp representing when the Terra Preference was last saved.
          format: int64
      description: Current user's choice of UI views.
    Profile:
      required:
      - firstName
      - institute
      - institutionalProgram
      - lastName
      - nonProfitStatus
      - pi
      - programLocationCity
      - programLocationCountry
      - programLocationState
      - title
      type: object
      properties:
        firstName:
          type: string
          description: User's first name
        lastName:
          type: string
          description: User's last name
        title:
          type: string
          description: User's title
        contactEmail:
          type: string
          description: User's contact email (if different from account email)
        institute:
          type: string
          description: User's home institution
        institutionalProgram:
          type: string
          description: User's institutional program
        programLocationCity:
          type: string
          description: User's program location city
        programLocationState:
          type: string
          description: User's program location state
        programLocationCountry:
          type: string
          description: User's program location country
        pi:
          type: string
          description: Principal Investigator
        nonProfitStatus:
          type: string
          description: User's program non-profit status
        termsOfService:
          type: string
          description: The Terms of Service url, "app.terra.bio/#terms-of-service", which a user must include to show they accept the Terms of Service
        department:
          type: string
          description: User's department within an institution
        interestInTerra:
          type: string
          description: A string of comma-separated values of why the User is interested in Terra
    BillingAccountRedirect:
      required:
      - redirect
      type: object
      properties:
        redirect:
          type: string
          description: URL to redirect to
      description: Google redirect URL to enable appropriate scopes
    BillingAccount:
      required:
      - accountName
      - displayName
      - firecloudHasAccess
      type: object
      properties:
        accountName:
          type: string
          description: name of billing account
        firecloudHasAccess:
          type: boolean
          description: whether the Firecloud service has been given access to this billing account
        displayName:
          type: string
          description: display name of billing account
      description: Details for a single billing account
    RegisterProfile:
      type: object
      properties:
        userId:
          type: string
          description: The user's subject id
        keyValuePairs:
          type: array
          items:
            $ref: '#/components/schemas/KeyValuePair'
    StackTraceElement:
      required:
      - className
      - fileName
      - lineNumber
      - methodName
      type: object
      properties:
        className:
          type: string
          description: class name
        methodName:
          type: string
          description: method name
        fileName:
          type: string
          description: source file name
        lineNumber:
          type: integer
          description: line number
          format: int32
      description: ''
    KeyValuePair:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
  securitySchemes:
    oidc:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL
    oidc_google_billing_scope:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL_WITH_GOOGLE_BILLING_SCOPE
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL_WITH_GOOGLE_BILLING_SCOPE