Nayya Connections API

openapi: 3.0.0
info:
  title: Accounts Benefits Connections API
  description: Accounts API
  version: '0.1'
  contact: {}
servers:
- url: https://integrate.nayya.com/accounts
  description: Production
- url: https://integrate.partners.nayya.com/accounts
  description: Partners
security:
- bearerAuth: []
tags:
- name: Connections
paths:
  /connections:
    post:
      operationId: add-connections
      parameters:
      - name: X-API-Version
        in: header
        required: false
        description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
        schema:
          type: string
          default: '1'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddConfiguredConnectionsDto'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfiguredConnectionsResponseDto'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
        '500':
          description: Internal Server Error
      summary: Add connections to an Account
      tags:
      - Connections
      x-scope:
      - create:configured-connections
  /employers/{employerId}/connections:
    post:
      operationId: add-connection-to-employer
      parameters:
      - name: employerId
        required: true
        in: path
        description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
        schema:
          type: string
      - name: X-API-Version
        in: header
        required: false
        description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
        schema:
          type: string
          default: '1'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddConnectionDto'
      responses:
        '200':
          description: Successfully added the connection to the partner employer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponseDto'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      summary: Add connection to an Employer
      tags:
      - Connections
      x-scope:
      - update:partner-employers
    delete:
      operationId: remove-connection-from-employer
      parameters:
      - name: employerId
        required: true
        in: path
        description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
        schema:
          type: string
      - name: X-API-Version
        in: header
        required: false
        description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
        schema:
          type: string
          default: '1'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveConnectionDto'
      responses:
        '200':
          description: Successfully removed the connection from the partner employer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployerResponseDto'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
      summary: Remove connection from an Employer
      tags:
      - Connections
      x-scope:
      - update:partner-employers
components:
  schemas:
    AddConfiguredConnectionsDto:
      type: object
      properties:
        connections:
          description: Array of connection configurations to add
          type: array
          items:
            $ref: '#/components/schemas/ConnectionConfigDto'
      required:
      - connections
    AddConnectionDto:
      type: object
      properties:
        connectionName:
          type: string
          description: The connection name to add
          example: google-oauth2
      required:
      - connectionName
    EmployerResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Employer ID
          example: 123e4567-e89b-12d3-a456-426614174000
        externalId:
          type: string
          nullable: true
          description: Employer external ID
          example: EMP-123
        name:
          type: string
          description: Employer name
          example: Acme Corporation
        description:
          type: string
          nullable: true
          description: Employer description
          example: A leading technology company
        streetAddress:
          type: string
          nullable: true
          description: Employer street address
          example: 123 Main Street
        city:
          type: string
          nullable: true
          description: Employer city
          example: San Francisco
        state:
          type: string
          nullable: true
          description: Employer state
          example: CA
        zipCode:
          type: string
          nullable: true
          description: Employer zip code
          example: '94105'
        ein:
          type: string
          nullable: true
          description: Employer EIN
          example: 12-3456789
        websiteUrl:
          type: string
          nullable: true
          description: Employer website URL
          example: https://www.acme.com
        phoneNumber:
          type: string
          nullable: true
          description: Employer phone number
          example: '+12125551234'
        logoUrl:
          type: string
          nullable: true
          description: Employer logo URL
          example: https://www.acme.com/logo.png
        benAdminButton:
          type: string
          nullable: true
          description: Employer ben admin button text
          example: Proceed to Enrollment
        benAdminLink:
          type: string
          nullable: true
          description: Employer ben admin link
          example: https://www.acme.com/ben-admin-link
        createdAt:
          format: date-time
          type: string
          description: Creation date
          example: '2024-03-20T00:00:00.000Z'
        updatedAt:
          format: date-time
          type: string
          description: Last update date
          example: '2024-03-20T00:00:00.000Z'
      required:
      - id
      - externalId
      - name
      - description
      - streetAddress
      - city
      - state
      - zipCode
      - ein
      - websiteUrl
      - phoneNumber
      - logoUrl
      - benAdminButton
      - benAdminLink
      - createdAt
      - updatedAt
    ConfiguredConnectionsResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Partner account ID
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Partner account name
          example: Acme Corporation
        description:
          type: string
          description: Partner account description
          example: A leading technology company
          nullable: true
        configuredConnections:
          description: Configured connections for the partner account
          type: array
          items:
            $ref: '#/components/schemas/ConnectionDto'
      required:
      - id
      - name
      - description
      - configuredConnections
    ConnectionDto:
      type: object
      properties:
        name:
          type: string
          description: Connection name
          example: google-oauth2
        assignMembershipOnLogin:
          type: boolean
          description: Whether to assign membership on login
          example: true
        showAsButton:
          type: boolean
          description: Whether to show as button
          example: true
        isSignupEnabled:
          type: boolean
          description: Whether signup is enabled
          example: true
      required:
      - name
    RemoveConnectionDto:
      type: object
      properties:
        connectionName:
          type: string
          description: The connection name to remove
          example: google-oauth2
      required:
      - connectionName
    ConnectionConfigDto:
      type: object
      properties:
        name:
          type: string
          description: The name of the connection configuration
          example: My SSO Connection
        type:
          type: string
          description: The type of connection
          enum:
          - sso
          - database
          example: sso
      required:
      - name
      - type
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token