Spectro Cloud auth API

openapi: 3.2.0
info:
  title: Local Management APIs activations Auth API
  version: v1
servers:
- url: https://edge-host-ip:5080
tags:
- name: auth
  x-displayName: Auth
paths:
  /v1/auth/authenticate:
    post:
      description: Creates a authentication request with the specified credentials
      operationId: v1Authenticate
      parameters:
      - description: Describes a way to set cookie from backend.
        in: query
        name: setCookie
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UserToken'
      summary: Authenticates the user for the specified crendentials
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1AuthLogin'
        description: Describes the credential details required for authentication
        required: true
  /v1/auth/mfa/devices:
    get:
      operationId: V1AuthMfaDevicesList
      responses:
        '200':
          description: (empty)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1MfaDevices'
      summary: V1AuthMfaDevicesList
      tags:
      - auth
      x-ApiScopes:
      - mfa
  /v1/auth/org:
    get:
      description: Returns the allowed login method and information with the organization details
      operationId: v1AuthOrg
      parameters:
      - in: query
        name: orgName
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1LoginResponse'
      summary: Returns the user organization details
      tags:
      - auth
  /v1/auth/org/{org}/oidc/callback:
    parameters:
    - description: Organization name
      in: path
      name: org
      required: true
      schema:
        type: string
    - description: Describes temporary and very short lived code sent by IDP to validate the token
      in: query
      name: code
      schema:
        type: string
    - description: Describes a state to validate and associate request and response
      in: query
      name: state
      schema:
        type: string
    - description: Describes a error code in case the IDP is not able to validate and authenticates the user
      in: query
      name: error
      schema:
        type: string
    - description: Describes a error in case the IDP is not able to validate and authenticates the user
      in: query
      name: error_description
      schema:
        type: string
    get:
      description: Returns the Authorization token for the palette. This is called by the IDP as a callback url after IDP authenticates the user with its server.
      operationId: V1OidcCallback
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UserToken'
      summary: Idp authorization code callback
      tags:
      - auth
  /v1/auth/org/{org}/oidc/logout:
    parameters:
    - description: Organization name
      in: path
      name: org
      required: true
      schema:
        type: string
    - description: Describes a state to validate and associate request and response
      in: query
      name: state
      schema:
        type: string
    get:
      description: Returns No Content. Works as a callback url after the IDP logout from their server.
      operationId: V1OidcLogout
      responses:
        '204':
          description: Ok response without content
          headers:
            AuditUid:
              description: Audit uid for the request
              schema:
                type: string
      summary: Identity provider logout url for the Oidc
      tags:
      - auth
  /v1/auth/org/{org}/saml/callback:
    parameters:
    - description: Organization name
      in: path
      name: org
      required: true
      schema:
        type: string
    - description: Deprecated.
      in: query
      name: authToken
      schema:
        type: string
    post:
      description: Returns the Authorization token for the palette. This is called by the SAML based IDP as a callback url after IDP authenticates the user with its server.
      operationId: V1SamlCallback
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UserToken'
      summary: Identity provider callback url for the SMAL authentication
      tags:
      - auth
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                SAMLResponse:
                  type: string
                  description: Describe the SAML compliant response sent by IDP which will be validated by Palette
                RelayState:
                  type: string
                  description: Describes a state to validate and associate request and response
  /v1/auth/org/{org}/saml/logout:
    parameters:
    - description: Organization name
      in: path
      name: org
      required: true
      schema:
        type: string
    - description: Deprecated.
      in: query
      name: authToken
      schema:
        type: string
    post:
      description: Returns No Content. Works as a callback url after the IDP logout from their server.
      operationId: V1SamlLogout
      responses:
        '204':
          description: Ok response without content
          headers:
            AuditUid:
              description: Audit uid for the request
              schema:
                type: string
      summary: Identity provider logout url for the SMAL
      tags:
      - auth
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                SAMLResponse:
                  type: string
                  description: Describe the SAML compliant response sent by IDP which will be validated by Palette to perform logout.
  /v1/auth/orgs:
    get:
      description: Returns a list of user's organizations details and login methods
      operationId: V1AuthOrgs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1Organizations'
      summary: Returns a list of user's organizations
      tags:
      - auth
  /v1/auth/password/{passwordToken}/activate:
    parameters:
    - description: Describes the expirable password token for the user to be used for authentication of user
      in: path
      name: passwordToken
      required: true
      schema:
        type: string
    patch:
      description: Updates and Activates user password with the help of password token
      operationId: v1PasswordActivate
      responses:
        '204':
          description: The resource was updated successfully
      summary: Updates and Activates the specified user password using the password token
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              properties:
                password:
                  description: Describes the new password for the user
                  format: password
                  type: string
              required:
              - password
              type: object
        required: true
  /v1/auth/password/{passwordToken}/reset:
    parameters:
    - description: Describes the expirable password token for the user to be used for authentication of user
      in: path
      name: passwordToken
      required: true
      schema:
        type: string
    patch:
      description: Updates the new user password with the help of password token
      operationId: v1PasswordReset
      responses:
        '204':
          description: The resource was updated successfully
      summary: Resets the user password using the password token
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              properties:
                password:
                  description: Describes the new password for the user
                  format: password
                  type: string
              required:
              - password
              type: object
        required: true
  /v1/auth/refresh/{token}:
    parameters:
    - description: Describes a way to set cookie from backend.
      in: query
      name: setCookie
      schema:
        type: boolean
        default: true
    - description: Non expired Authorization token
      in: path
      name: token
      required: true
      schema:
        type: string
    get:
      description: Returns a new token within refresh timeout and same session id is maintained
      operationId: v1AuthRefresh
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UserToken'
      summary: Refreshes authentication token
      tags:
      - auth
  /v1/auth/sso/idps:
    get:
      description: Returns a list of predefined Identity Provider (IDP)
      operationId: V1SsoIdps
      responses:
        '200':
          description: (empty)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1IdentityProviders'
      summary: Returns a list of predefined Identity Provider (IDP)
      tags:
      - auth
  /v1/auth/sso/logins:
    get:
      description: Returns a list of supported sso logins and their authentication mechanism
      operationId: V1SsoLogins
      parameters:
      - in: query
        name: org
        schema:
          type: string
      responses:
        '200':
          description: (empty)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SsoLogins'
      summary: Returns a list of supported sso logins
      tags:
      - auth
  /v1/auth/sso/providers:
    get:
      description: Returns a list of supported sso auth providers
      operationId: V1AuthSsoProviders
      responses:
        '200':
          description: (empty)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1SsoLogins'
      summary: Returns a list of supported sso auth providers
      tags:
      - auth
  /v1/auth/sso/{ssoApp}/callback:
    parameters:
    - description: Describes the sso app use to login into the system
      in: path
      name: ssoApp
      required: true
      schema:
        type: string
    - description: Describes temporary and very short lived code sent by IDP to validate the token
      in: query
      name: code
      schema:
        type: string
    - description: Describes a state to validate and associate request and response
      in: query
      name: state
      schema:
        type: string
    - description: Describes a error code in case the IDP is not able to validate and authenticates the user
      in: query
      name: error
      schema:
        type: string
    - description: Describes a error in case the IDP is not able to validate and authenticates the user
      in: query
      name: error_description
      schema:
        type: string
    get:
      description: Returns Authorization token. Works as a callback url for the system defined sso apps
      operationId: V1SsoCallback
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1UserToken'
      summary: Returns Authorization token. Works as a callback url for the system defined sso apps
      tags:
      - auth
  /v1/auth/user/org/forgot:
    get:
      description: Returns No Content. Sends the user organization(s) information via email
      operationId: V1AuthUserOrgForgot
      parameters:
      - description: Describes user's email id for sending organzation(s) details via email.
        in: query
        name: emailId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Ok response without content
          headers:
            AuditUid:
              description: Audit uid for the request
              schema:
                type: string
      summary: Returns No Content. Sends the user organization information via email
      tags:
      - auth
  /v1/auth/user/password/reset:
    post:
      description: Creates request to reset password via email. Password reset email will be sent to the user. Sends 204 No Content.
      operationId: v1PasswordResetRequest
      responses:
        '204':
          description: Ok response without content
          headers:
            AuditUid:
              description: Audit uid for the request
              schema:
                type: string
      summary: Creates request to reset password via email
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              properties:
                emailId:
                  description: Describes email if for which password reset email has to be sent
                  type: string
              required:
              - emailId
              type: object
        required: true
components:
  schemas:
    v1LoginResponse:
      description: Returns the allowed login method and information with the organization details
      properties:
        appEnv:
          description: Describes the env type. Possible values [ saas, self-hosted, quick-start, enterprise, airgap]
          type: string
        authType:
          description: Describes the default mode of authentication. Possible values [password, sso]
          enum:
          - password
          - sso
          type: string
        orgName:
          description: Organization name.
          type: string
        redirectUrl:
          description: Describes the default redirect Url for authentication. If authType is sso, it will have tenant configured saml/oidc idp url else it will be users organization url
          type: string
          x-omitempty: false
        rootDomain:
          description: Describes the domain url on which the saas is available
          type: string
        securityMode:
          description: Describes which security mode is enabled
          type: string
        ssoLogins:
          $ref: '#/components/schemas/v1SsoLogins'
          description: Just Inside. Describes the allowed social logins
        totalTenants:
          description: Describes the total number of tenant present in the system
          format: int64
          type: number
      type: object
    v1MfaDeviceMeta:
      properties:
        creationTimestamp:
          $ref: '#/components/schemas/v1Time'
        deviceName:
          type: string
      type: object
    v1IdentityProvider:
      description: Describes a predefined Identity Provider (IDP)
      properties:
        id:
          type: string
        name:
          type: string
      type: object
    v1UserToken:
      description: Returns the Authorization token. To be used for further api calls
      properties:
        Authorization:
          description: Describes the authentication token in jwt format.
          type: string
        isMfa:
          description: Indicates the authentication flow using MFA
          type: boolean
          x-omitempty: false
      type: object
    v1Organization:
      description: Describes user's organization details
      properties:
        authType:
          description: Describes user's enabled authorization mode
          type: string
        name:
          description: Describes user's organization name
          type: string
        redirectUrl:
          description: Describes user's organization authentication url
          type: string
        ssoLogins:
          $ref: '#/components/schemas/v1SsoLogins'
          description: Describes a list of allowed social logins for the organization
      type: object
    v1Time:
      description: Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON.  Wrappers are provided for many of the factory methods that the time package offers.
      format: date-time
      type: string
    v1SsoLogin:
      description: Describes the allowed sso login details
      properties:
        displayName:
          description: Describes the display name for the sso login
          type: string
        logo:
          description: Describes the url path for the sso login
          type: string
        name:
          description: Describes the processed name for the sso login
          type: string
        redirectUri:
          description: Describes the sso login url for the authentication
          type: string
      type: object
    v1IdentityProviders:
      description: Describes a list of predefined Identity Provider (IDP)
      items:
        $ref: '#/components/schemas/v1IdentityProvider'
      type: array
      uniqueItems: true
    v1SsoLogins:
      description: Describes the allowed sso logins
      items:
        $ref: '#/components/schemas/v1SsoLogin'
      type: array
      uniqueItems: true
    v1AuthLogin:
      description: Describes the credential details required for authentication
      properties:
        emailId:
          description: Describes the email id required for the user to authenticate
          type: string
        org:
          description: Describes the user's organization name to login
          type: string
        password:
          description: Describes the password required for the user to authenticate
          format: password
          type: string
      type: object
    v1MfaDevices:
      items:
        $ref: '#/components/schemas/v1MfaDeviceMeta'
      type: array
    v1Organizations:
      description: Returns a list of user's organizations details and login methods
      properties:
        organizations:
          description: Describes a list of user's organization
          items:
            $ref: '#/components/schemas/v1Organization'
          type: array
          uniqueItems: true
      type: object
  securitySchemes:
    Authorization:
      description: JWT authorization token obtained using /v1/users/default/login API
      type: apiKey
      name: Authorization
      in: header