Forsta Auth API

openapi: 3.2.0
info:
  title: Forsta Auth API
  version: ''
  description: 'Operations tagged Auth across 2 of this provider''s published API definitions: forsta-panel-management-community-openapi.yml, forsta-panel-management-integration-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{server}
  description: Replace server with your instance domain.
  variables:
    server:
      default: staging.panel.dev.focusvision.com/
      description: Server domain
tags:
- name: Auth
paths:
  /api.pro#method=portal.auth.login:
    post:
      operationId: portal.auth.login
      summary: Create a panelist session
      description: Create a panelist session and return panelist information needed for future API requests. The session remains active for 60 minutes. For existing sessions, a login request resets the session timer back to 60 minutes. Another way to reset the session's expiration timer is by making a request to /api.pro?method=portal.auth.validate
      tags:
      - Auth
      security: []
      parameters:
      - $ref: '#/components/parameters/method'
        schema:
          enum:
          - portal.auth.login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                panelid:
                  type: integer
                  description: The panelid the session will log as the current panel.
                portalid:
                  type: integer
                  description: The portalid the session will log as the current community.
                username:
                  type: string
                  description: The email address associated with the panelist.
                password:
                  type: string
                  description: The password associated with the panelist.
              required:
              - panelid
              - portalid
              - username
              - password
            example:
              panelid: 1
              portalid: 1
              username: demo
              password: demo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error'
                - type: object
                  properties:
                    success:
                      type: boolean
                      description: The login was successful.
                    seskey:
                      type: string
                      description: The sessionKey of the user session.
                    panelistid:
                      type: integer
                      description: The id of the panelist who has logged in.
                    email:
                      type: string
                      description: The email address of the panelist who has logged in.
                    fullname:
                      type: string
                      description: The full name of the panelist who has logged in.
                    firstname:
                      type: string
                      description: The first name of the panelist who has logged in.
                    lastname:
                      type: string
                      description: The last name of the panelist who has logged in.
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                    seskey: ce512c91
                    panelistid: 15
                    email: demo@example.com
                    fullname: Demo Panelist
                    firstname: Demo
                    lastname: Panelist
                error-0:
                  description: Panelist with supplied username is not found.
                  summary: Username incorrect
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-1:
                  description: The password entered for panelist is not correct.
                  summary: Password incorrect
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-2:
                  description: There have been 255 failed attempts from this IP address within the past 15 minutes.
                  summary: IP locked
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-3:
                  description: Panelist is not confirmed.
                  summary: Panelist not confirmed
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-4:
                  description: If community setting "Allow login for unsubscribed panelist" is "No" and panelist is not subscribed.
                  summary: Panelist not subscribed
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-5:
                  description: If community setting "Allow login for blacklisted panelist" is "No" and panelist is blacklisted.
                  summary: Panelist blacklisted
                  value:
                    success: false
                    error: Invalid username/password.
                    errno: '0'
                error-6:
                  description: The supplied portal ID is invalid for panelist.
                  summary: Portal ID incorrect
                  value:
                    success: false
                    error: The supplied community portal ID invalid.
                    errno: '20102'
    servers:
    - url: https://{server}
      description: Replace server with your instance domain.
      variables:
        server:
          default: staging.panel.dev.focusvision.com/
          description: Server domain
  /api.pro#method=portal.auth.logout:
    post:
      operationId: portal.auth.logout
      summary: Logout the current
      description: Logout of the current open API session.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/method'
        schema:
          enum:
          - portal.auth.logout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                seskey:
                  type: string
                  description: A valid login hash.
              required:
              - seskey
            example:
              seskey: ce512c91
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error'
                - type: object
                  properties:
                    success:
                      type: boolean
                      description: The logout was successful.
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                error-0:
                  description: Session key is not in correct format.
                  summary: Session invalid
                  value:
                    success: false
                    error: Session string is invalid
                    errno: '20101'
                error-1:
                  description: Session is not valid or is not found for supplied session key.
                  summary: Session invalid
                  value:
                    success: false
                    error: Session invalid
                    errno: '30100'
                error-2:
                  description: Session has expired.
                  summary: Session expired
                  value:
                    success: false
                    error: Session expired
                    errno: '30100'
                error-3:
                  description: Session is not found or is expired for supplied session key.
                  summary: Session incorrect
                  value:
                    success: false
                    error: Session not found
                    errno: '30200'
      security:
      - ApiKey: []
    servers:
    - url: https://{server}
      description: Replace server with your instance domain.
      variables:
        server:
          default: staging.panel.dev.focusvision.com/
          description: Server domain
  /api.pro#method=portal.auth.validate:
    post:
      operationId: portal.auth.validate
      summary: Checks the current seskey
      description: Checks that the current seskey is valid and return panelist information needed for future API requests.
      tags:
      - Auth
      parameters:
      - $ref: '#/components/parameters/method'
        schema:
          enum:
          - portal.auth.validate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                seskey:
                  type: string
                  description: A valid login hash.
              required:
              - seskey
            example:
              seskey: ce512c91
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error'
                - type: object
                  properties:
                    success:
                      type: boolean
                      description: The validation was successful.
                    panelistid:
                      type: integer
                      description: The panelistid of the validated panelist
                    email:
                      type: string
                      description: The email address of the validated panelist.
                    fullname:
                      type: string
                      description: The full name of the validated panelist.
                    seskey:
                      type: string
                      description: A valid login hash.
              examples:
                success:
                  summary: Success
                  value:
                    success: true
                    seskey: ce512c91
                    panelistid: 15
                    email: demo@example.com
                    fullname: Demo Panelist
                error-0:
                  description: Session key is not in correct format.
                  summary: Session invalid
                  value:
                    success: false
                    error: Session string is invalid
                    errno: '20101'
                error-1:
                  description: Session is not valid or is not found for supplied session key.
                  summary: Session invalid
                  value:
                    success: false
                    error: Session invalid
                    errno: '30100'
                error-2:
                  description: Session has expired.
                  summary: Session expired
                  value:
                    success: false
                    error: Session expired
                    errno: '30100'
      security:
      - ApiKey: []
    servers:
    - url: https://{server}
      description: Replace server with your instance domain.
      variables:
        server:
          default: staging.panel.dev.focusvision.com/
          description: Server domain
  /api/integration/sessions:
    post:
      operationId: createSession
      summary: Create a new session
      description: 'Create a new session token that can be used to authenticate later requests.

        The session remains active for 30 minutes. For existing sessions, any new request to the API resets the session timer back to 30 minutes.

        In order to obtain credentials, you must create an API key in “API Key Management” under the user icon menu.'
      tags:
      - Auth
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              properties:
                username:
                  description: The Client Id you get from API key manager module.
                  type: string
                  example: 3e159fcb-d2e6-4581-a1bb-c2d934c0aaaa
                password:
                  description: The secret you get from API key manager module.
                  type: string
                  example: 677621b3-a999-4ec9-8d04-49452eb57777
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_key:
                    description: 'The `session_key` value returned in the response can be used as the `sessionKey`

                      parameter in `DELETE /api/integration/sessions/{sessionKey}`.

                      '
                    example: 5a15852c564933807bbd36da58071063
                    type: string
              examples:
                success:
                  summary: Success
                  value:
                    session_key: 5a15852c564933807bbd36da58071063
        '400':
          description: "Bad request.   \nCheck that the \"username\" and \"password\" fields are present.\n"
        '401':
          description: "Unauthorized.   \nCould be one of the following:\n\n  - The supplied client id was not found.\n  - The supplied secret was empty or incorrect.\n  - There have been too many failed attempts from this IP address within a certain time frame.\n"
        '403':
          description: "Forbidden.   \nThe IP address is not allowed access.\n"
    servers:
    - url: https://{server}
      description: Replace server with your instance domain.
      variables:
        server:
          default: staging.panel.dev.focusvision.com/
          description: Server domain
  /api/integration/sessions/{sessionKey}:
    delete:
      operationId: terminateSession
      summary: Terminate an existing session
      description: Terminate an existing session by invalidating a `session_key`
      tags:
      - Auth
      security:
      - BearerAuth: []
      parameters:
      - name: sessionKey
        in: path
        required: true
        description: sessionKey
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Access token is missing or invalid
        '404':
          description: The supplied resource id was not found
    servers:
    - url: https://{server}
      description: Replace server with your instance domain.
      variables:
        server:
          default: staging.panel.dev.focusvision.com/
          description: Server domain
components:
  schemas:
    error:
      type: object
      properties:
        success:
          type: boolean
        error:
          description: The error message.
          type: string
        errno:
          description: The error code.
          type: string
  parameters:
    method:
      name: method
      in: query
      required: true
      description: Method
      schema:
        type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: seskey
    BearerAuth:
      type: http
      scheme: bearer
x-refined-from:
- forsta-panel-management-community-openapi.yml
- forsta-panel-management-integration-openapi.yml
x-tagGroups:
- name: Autoclose
  tags:
  - Autoclose
- name: Data Input and Output
  tags:
  - Data
  - Data Feed
  - Response Summary
  - Modifying Data
  - Datasources
  - Datasources Data
  - Umerge
- name: Survey Metadata
  tags:
  - Simulated Data
  - Survey State
  - Survey Evaluate
  - Survey Quotas
  - Survey Files
  - Survey Warnings
  - Survey Terms
  - Survey Subscribers
  - Survey Users
  - Survey Tasks
- name: Panels
  tags:
  - Panel Data
  - Panel Datapoints
  - Survey Panels
- name: Research Hub
  tags:
  - Users
  - Companies
  - Categories
  - Surveys
  - Panels
  - Crosstabs
  - Archives
  - Archival Reports
  - API Keys
  - Usage
  - Warnings Summary
- name: Crosstabs
  tags:
  - Crosstabs Configuration
  - Crosstabs Execution
  - Crosstabs Nets
  - Saved Crosstabs
  - Crosstabs Table Settings
  - Crosstabs Validation
  - Crosstabs Rim Weighting
- name: Dashboards
  tags:
  - Dashboards
- name: DQ APIs
  tags:
  - DQ-Specific API Calls
  - MaxDiff API Calls
  - Discrete Choice Model API Calls
  - Media Testimonial API Calls
- name: Response Summary
  tags:
  - Share Link
- name: Sample Management
  tags:
  - Bounced Emails
  - Participant Sources
- name: Distribution
  tags:
  - Email Distribution
  - SFTP Distribution
  - Slack Distribution
- name: Campaign Manager
  tags:
  - Campaigns
  - Campaign Email Invites
  - Campaign Exports
  - Campaign Lists
  - Shared Campaign Lists
  - Campaign Sends
  - Campaign Status Lists
  - Supression Lists
- name: Question Library
  tags:
  - Company Element
  - Company Elements
  - Survey Elements
  - Survey Element Report Settings
- name: Language Manager
  tags:
  - LM Application Data
  - LM Application Translations
  - Translation Resources
  - Translations
  - Translation Deltas
  - Translation Reservations
  - Primary Survey Language
  - Other Survey Languages
  - Unused Survey Languages
- name: Project Parameters
  tags:
  - Available Project Parameters
  - Saved Project Parameters
  - Project Parameters Configuration
- name: Multi-User Editing
  tags:
  - Available Sections
  - Check Out Section
  - Check In Section
  - Sync Section
  - Section Editor
  - Abandon Section
  - Validate Section
- name: Video Management
  tags:
  - Videos
  - Watermarked Videos
- name: Miscellaneous
  tags:
  - System Information
  - Logic Nodes
  - Logic Events
  - CATI
  - Global Search
  - Miscellaneous