FusionAuth Login API

openapi: 3.2.0
info:
  version: 1.66.0
  title: FusionAuth Api Key Login API
  description: This is a FusionAuth server. Find out more at [https://fusionauth.io](https://fusionauth.io). You need to [set up an API key](https://fusionauth.io/docs/v1/tech/apis/authentication#managing-api-keys) in the FusionAuth instance you are using to test out the API calls.
  license:
    name: Apache2
servers:
- url: http://localhost:9011
- url: https://sandbox.fusionauth.io
security:
- ApiKeyAuth: []
tags:
- name: Login
paths:
  /api/login:
    post:
      description: Authenticates a user to FusionAuth.   This API optionally requires an API key. See <code>Application.loginConfiguration.requireAuthentication</code>.
      operationId: loginWithId
      parameters:
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - Login
    put:
      description: Sends a ping to FusionAuth indicating that the user was automatically logged into an application. When using FusionAuth's SSO or your own, you should call this if the user is already logged in centrally, but accesses an application where they no longer have a session. This helps correctly track login counts, times and helps with reporting.
      operationId: loginPingWithRequestWithId
      parameters:
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginPingRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - Login
  /api/login/{userId}/{applicationId}:
    put:
      description: Sends a ping to FusionAuth indicating that the user was automatically logged into an application. When using FusionAuth's SSO or your own, you should call this if the user is already logged in centrally, but accesses an application where they no longer have a session. This helps correctly track login counts, times and helps with reporting.
      operationId: loginPingWithId
      parameters:
      - name: callerIPAddress
        in: query
        schema:
          type: string
        description: The IP address of the end-user that is logging in. If a null value is provided the IP address will be that of the client or last proxy that sent the request.
      - name: userId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the user that was logged in.
      - name: applicationId
        in: path
        schema:
          type: string
        required: true
        description: The Id of the application that they logged into.
      - in: header
        name: X-FusionAuth-TenantId
        description: The unique Id of the tenant used to scope this API request. Only required when there is more than one tenant and the API key is not tenant-scoped.
        required: false
        schema:
          type: string
          format: UUID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      tags:
      - Login
components:
  schemas:
    Errors:
      description: Standard error domain object that can also be used as the response from an API call.
      type: object
      properties:
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        generalErrors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    User:
      description: The public, global view of a User. This object contains all global information about the user including birthdate, registration information  preferred languages, global attributes, etc.
      type: object
      properties:
        preferredLanguages:
          type: array
          items:
            $ref: '#/components/schemas/Locale'
        active:
          type: boolean
        birthDate:
          $ref: '#/components/schemas/LocalDate'
        cleanSpeakId:
          type: string
          format: uuid
        data:
          type: object
          additionalProperties:
            type: object
        email:
          type: string
        expiry:
          $ref: '#/components/schemas/ZonedDateTime'
        firstName:
          type: string
        fullName:
          type: string
        imageUrl:
          type: string
          format: URI
        insertInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        lastName:
          type: string
        lastUpdateInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        middleName:
          type: string
        mobilePhone:
          type: string
        parentEmail:
          type: string
        phoneNumber:
          type: string
        tenantId:
          type: string
          format: uuid
        timezone:
          $ref: '#/components/schemas/ZoneId'
        twoFactor:
          $ref: '#/components/schemas/UserTwoFactorConfiguration'
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/GroupMember'
        registrations:
          type: array
          items:
            $ref: '#/components/schemas/UserRegistration'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/UserIdentity'
        breachedPasswordLastCheckedInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        breachedPasswordStatus:
          $ref: '#/components/schemas/BreachedPasswordStatus'
        connectorId:
          type: string
          format: uuid
        encryptionScheme:
          type: string
        factor:
          type: integer
        id:
          type: string
          format: uuid
        lastLoginInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        password:
          type: string
        passwordChangeReason:
          $ref: '#/components/schemas/ChangePasswordReason'
        passwordChangeRequired:
          type: boolean
        passwordLastUpdateInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        salt:
          type: string
        uniqueUsername:
          type: string
        username:
          type: string
        usernameStatus:
          $ref: '#/components/schemas/ContentStatus'
        verified:
          type: boolean
        verifiedInstant:
          $ref: '#/components/schemas/ZonedDateTime'
    ContentStatus:
      description: Status for content like usernames, profile attributes, etc.
      type: string
      enum:
      - ACTIVE
      - PENDING
      - REJECTED
    UserRegistration:
      description: User registration information for a single application.
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            type: object
        preferredLanguages:
          type: array
          items:
            $ref: '#/components/schemas/Locale'
        tokens:
          type: object
          additionalProperties:
            type: string
        applicationId:
          type: string
          format: uuid
        authenticationToken:
          type: string
        cleanSpeakId:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        insertInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        lastLoginInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        lastUpdateInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        roles:
          type: array
          uniqueItems: true
          items: {}
        timezone:
          $ref: '#/components/schemas/ZoneId'
        username:
          type: string
        usernameStatus:
          $ref: '#/components/schemas/ContentStatus'
        verified:
          type: boolean
        verifiedInstant:
          $ref: '#/components/schemas/ZonedDateTime'
    MetaData:
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            type: object
        device:
          $ref: '#/components/schemas/DeviceInfo'
        scopes:
          type: array
          uniqueItems: true
          items: {}
    GroupMember:
      description: A User's membership into a Group
      type: object
      properties:
        data:
          type: object
          additionalProperties:
            type: object
        groupId:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        insertInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        userId:
          type: string
          format: uuid
    BreachedPasswordStatus:
      description: ''
      type: string
      enum:
      - None
      - ExactMatch
      - SubAddressMatch
      - PasswordOnly
      - CommonPassword
    LoginResponse:
      description: ''
      type: object
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/LoginPreventedResponse'
        changePasswordId:
          type: string
        changePasswordReason:
          $ref: '#/components/schemas/ChangePasswordReason'
        configurableMethods:
          type: array
          items:
            type: string
        emailVerificationId:
          type: string
        identityVerificationId:
          type: string
        methods:
          type: array
          items:
            $ref: '#/components/schemas/TwoFactorMethod'
        pendingIdPLinkId:
          type: string
        refreshToken:
          type: string
        refreshTokenId:
          type: string
          format: uuid
        registrationVerificationId:
          type: string
        state:
          type: object
          additionalProperties:
            type: object
        threatsDetected:
          type: array
          uniqueItems: true
          items: {}
        token:
          type: string
        tokenExpirationInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        trustToken:
          type: string
        twoFactorId:
          type: string
        twoFactorTrustId:
          type: string
        user:
          $ref: '#/components/schemas/User'
    Locale:
      description: A Locale object represents a specific geographical, political, or cultural region.
      example: en_US
      type: string
    ZonedDateTime:
      description: 'The number of milliseconds since the unix epoch: January 1, 1970 00:00:00 UTC. This value is always in UTC.'
      example: '1659380719000'
      type: integer
      format: int64
    DeviceInfo:
      description: ''
      type: object
      properties:
        description:
          type: string
        lastAccessedAddress:
          type: string
        lastAccessedInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        name:
          type: string
        type:
          type: string
    UserIdentity:
      description: ''
      type: object
      properties:
        displayValue:
          type: string
        insertInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        lastLoginInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        lastUpdateInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        moderationStatus:
          $ref: '#/components/schemas/ContentStatus'
        primary:
          type: boolean
        type:
          $ref: '#/components/schemas/IdentityType'
        value:
          type: string
        verified:
          type: boolean
        verifiedInstant:
          $ref: '#/components/schemas/ZonedDateTime'
        verifiedReason:
          $ref: '#/components/schemas/IdentityVerifiedReason'
    Error:
      description: Defines an error.
      type: object
      properties:
        code:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
        message:
          type: string
    ZoneId:
      description: Timezone Identifier
      example: America/Denver
      pattern: ^w+/w+$
      type: string
    LocalDate:
      description: A date without a time-zone in the ISO-8601 calendar system, such as 2007-12-03.
      example: '2007-12-03'
      pattern: ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$
      type: string
    TOTPAlgorithm:
      type: string
      enum:
      - HmacSHA1
      - HmacSHA256
      - HmacSHA512
    LoginPreventedResponse:
      description: The summary of the action that is preventing login to be returned on the login response.
      type: object
      properties:
        actionId:
          type: string
          format: uuid
        actionerUserId:
          type: string
          format: uuid
        expiry:
          $ref: '#/components/schemas/ZonedDateTime'
        localizedName:
          type: string
        localizedOption:
          type: string
        localizedReason:
          type: string
        name:
          type: string
        option:
          type: string
        reason:
          type: string
        reasonCode:
          type: string
    IdentityType:
      description: Model identity types provided by FusionAuth.
      type: object
      properties:
        name:
          type: string
    AuthenticatorConfiguration:
      description: ''
      type: object
      properties:
        algorithm:
          $ref: '#/components/schemas/TOTPAlgorithm'
        codeLength:
          type: integer
        timeStep:
          type: integer
    LoginPingRequest:
      description: Login Ping API request object.
      type: object
      properties:
        userId:
          type: string
          format: uuid
        applicationId:
          type: string
          format: uuid
        ipAddress:
          type: string
        metaData:
          $ref: '#/components/schemas/MetaData'
        newDevice:
          type: boolean
        noJWT:
          type: boolean
    ChangePasswordReason:
      description: ''
      type: string
      enum:
      - Administrative
      - Breached
      - Expired
      - Validation
    LoginRequest:
      description: Login API request object.
      type: object
      properties:
        loginId:
          type: string
        loginIdTypes:
          type: array
          items:
            type: string
        oneTimePassword:
          type: string
        password:
          type: string
        twoFactorTrustId:
          type: string
        applicationId:
          type: string
          format: uuid
        ipAddress:
          type: string
        metaData:
          $ref: '#/components/schemas/MetaData'
        newDevice:
          type: boolean
        noJWT:
          type: boolean
    UserTwoFactorConfiguration:
      description: ''
      type: object
      properties:
        methods:
          type: array
          items:
            $ref: '#/components/schemas/TwoFactorMethod'
        recoveryCodes:
          type: array
          items:
            type: string
    TwoFactorMethod:
      description: ''
      type: object
      properties:
        authenticator:
          $ref: '#/components/schemas/AuthenticatorConfiguration'
        email:
          type: string
        id:
          type: string
        lastUsed:
          type: boolean
        method:
          type: string
        mobilePhone:
          type: string
        secret:
          type: string
    IdentityVerifiedReason:
      description: Models the reason that {@link UserIdentity#verified} was set to true or false.
      type: string
      enum:
      - Skipped
      - Trusted
      - Unverifiable
      - Implicit
      - Pending
      - Completed
      - Disabled
      - Administrative
      - Import
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT