login.raml

#%RAML 1.0
title: Login
version: v7.0
baseUri: http://github.com/org/folio/mod-auth/login_module

documentation:
  - title: mod-login API
    content: This module provides a username/password based login mechanism for FOLIO credentials

types:
  credential: !include credentials.json
  loginCredentials: !include loginCredentials.json
  updateCredentials: !include updateCredentials.json
  loginAttempts: !include loginAttempts.json
  errors: !include raml-util/schemas/errors.schema
  credentialsHistory: !include credentialsHistory.json
  password: !include password.json
  passwordValid: !include passwordValid.json
  passwordReset: !include passwordResetAction.json
  passwordCreate: !include passwordCreateAction.json
  responseCreateAction: !include responseCreateAction.json
  responseResetAction: !include responseResetAction.json
  configurations: !include configurations.json
  configResponse: !include configResponse.json
  logEvent: !include logEvent.json
  logEvents: !include logEventCollection.json
  logResponse: !include logResponse.json
  loginResponse: !include loginResponse.json
  loginResponseWithExpiry: !include loginResponseWithExpiry.json
  credentialsExistence: !include credentialsExistence.json
  userTenant: !include userTenant.json

traits:
  validate: !include raml-util/traits/validation.raml
  pageable:
    queryParameters:
      length:
        description: "The maximum number of results to return."
        required: false
        type: integer
        example: 10
        minimum: 1
        default: 10
        maximum: 2147483647
      start:
        description: "The starting index in a list of results (starts at one)."
        required: false
        type: integer
        minimum: 1
        default: 1
        maximum: 2147483647
  sortable:
    queryParameters:
      sortBy:
        description: "A comma-separated list of fieldnames to sort by"
        required: false
        type: string
  queryable:
    queryParameters:
      query:
        description: "A query string to filter users based on matching criteria in fields."
        required: false
        type: string
/authn:
  /loginAttempts:
    /{id}:
      get:
        description: Get login attempts for a single user
        responses:
          200:
            body:
              application/json:
                schema: loginAttempts
          404:
            description: "User not found"
            body:
              text/plain:
                example: "User not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
  /login:
    post:
      description: Deprecated. Please use login-with-expiry instead. Will be removed in a future release. Get a new login token without an expiration (legacy endpoint)
      headers:
        User-Agent:
        X-Forwarded-For:
      body:
        application/json:
          type: loginCredentials
      responses:
        201:
          headers:
            x-okapi-token:
          body:
            application/json:
              type: loginResponse
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        404:
          description: "Not found"
          body:
            text/plain:
              example: "Not found"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /login-with-expiry:
    post:
      description: Get an expiring refresh and access token
      headers:
        User-Agent:
        X-Forwarded-For:
      body:
        application/json:
          type: loginCredentials
      responses:
        201:
          headers:
            Set-Cookie:
              description: access token cookie and refresh token cookie
              example: |
                Set-Cookie: folioAccessToken=abc.def.ghi; Max-Age=600; Expires=Tue, 23 Jan 2024 15:15:49 GMT; Path=/; Secure; HTTPOnly; SameSite=Strict
                Set-Cookie: folioRefreshToken=rst.uvw.xyz; Max-Age=604800; Expires=Tue, 30 Jan 2024 15:05:49 GMT; Path=/authn; Secure; HTTPOnly; SameSite=Strict
          body:
            application/json:
              type: loginResponseWithExpiry
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        404:
          description: "Not found"
          body:
            text/plain:
              example: "Not found"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /refresh:
    post:
      description: Get a new refresh and access token
      headers:
        Cookie:
          description: The Cookie header that must contain the refresh token cookie; all other cookies like the access token cookie are ignored
          example: |
            Cookie: folioRefreshToken=rst.uvw.xyz; folioAccessToken=abc.def.ghi
      responses:
        201:
          headers:
            Set-Cookie:
              description: access token cookie and refresh token cookie
              example: |
                Set-Cookie: folioAccessToken=abc.def.ghi; Max-Age=600; Expires=Tue, 23 Jan 2024 15:15:49 GMT; Path=/; Secure; HTTPOnly; SameSite=Strict
                Set-Cookie: folioRefreshToken=rst.uvw.xyz; Max-Age=604800; Expires=Tue, 30 Jan 2024 15:05:49 GMT; Path=/authn; Secure; HTTPOnly; SameSite=Strict
          body:
            application/json:
              type: loginResponseWithExpiry
        400:
          description: "Bad request"
          body:
            application/json:
              example: "Bad request"
        422:
          description: "Unprocessable entity. mod-authtoken has returned a 400 level response."
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /logout:
    post:
      description: Logs the user out on their current device
      headers:
        Cookie:
          description: The Cookie header that must contain the refresh token cookie; all other cookies like the access token cookie are ignored
          example: |
            Cookie: folioRefreshToken=rst.uvw.xyz; folioAccessToken=abc.def.ghi
      responses:
        204:
        400:
          description: "Bad request"
          body:
            application/json:
              example: "Bad request"
        422:
          description: "Unprocessable entity. mod-authtoken has returned a 400 level response."
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /logout-all:
    post:
      description: Logs the user out on all of their devices
      responses:
        204:
        400:
          description: "Bad request"
          body:
            application/json:
              example: "Bad request"
        422:
          description: "Unprocessable entity. mod-authtoken has returned a 400 level response."
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /update:
    post:
      description: Self-update existing credentials.  N.B. A non-empty password must be provided.
      headers:
        User-Agent:
        X-Forwarded-For:
      body:
        application/json:
          type: updateCredentials
      responses:
        204:
          description: "Successful update"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        401:
          description: "Unauthorized"
          body:
            text/plain:
              example: "Unauthorized"
        422:
          description: "Unprocessable Entity"
          body:
            application/json:
              type: errors
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /credentials:
    post:
      description: Add a new login to the system. N.B. A non-empty password must be provided.
      is: [validate]
      body:
        application/json:
          type: loginCredentials
      responses:
        201:
          description: "Success"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: "Bad request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    delete:
      description: Remove a user's login credentials from the system
      is: [validate]
      queryParameters:
        userId:
          description: "User Id"
          pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          required: true
      responses:
        204:
          description: "Success"
        404:
          description: "User not found"
          body:
            text/plain:
              example: "User not found"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /password:
    /repeatable:
          post:
            description: Validate if password has been used before.
            body:
              application/json:
                type: password
            responses:
              200:
                body:
                  application/json:
                    type: passwordValid
                    example:
                      result: invalid
              500:
                description: "Internal server error"
                body:
                  text/plain:
                    example: "Internal server error"
  /reset-password:
    post:
      description: Resets password for user in record and deletes action record
      headers:
        User-Agent:
        X-Forwarded-For:
      body:
        application/json:
          schema: passwordReset
      responses:
        201:
          body:
            application/json:
              type: responseResetAction
        400:
          body:
            text/plain:
              example: "Bad Request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
  /password-reset-action:
    post:
      description: Saves action to storage
      body:
        application/json:
          schema: passwordCreate
      responses:
        201:
          body:
            application/json:
              type: responseCreateAction
        400:
          body:
            text/plain:
              example: "Bad Request"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"
    /{actionId}:
      get:
        description: Retrieves action record by id
        responses:
          200:
            body:
              application/json:
                schema: passwordCreate
          400:
            body:
              text/plain:
                example: "Bad Request"
          404:
            body:
              text/plain:
                example: "Not Found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
  /log:
    /events:
      get:
        description: Returns a list of events retrieved from storage
        is: [
          pageable,
          queryable
        ]
        responses:
          200:
            body:
              application/json:
                schema: logEvents
          204:
            body:
              text/plain:
                example: "No Content"
          404:
            description: "Event not found"
            body:
              text/plain:
                example: "Event not found"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      post:
        description: Saves received event into the storage
        body:
          application/json:
            schema: logEvent
        responses:
          201:
            body:
              application/json:
                schema: logResponse
          204:
            body:
              text/plain:
                example: "No Content"
          500:
            description: "Internal server error"
            body:
              text/plain:
                example: "Internal server error"
      /{id}:
        delete:
          description: Removes events by filter
          responses:
            200:
              body:
                application/json:
                  schema: logResponse
            204:
              body:
                text/plain:
                  example: "No Content"
            404:
              description: "Event not found"
              body:
                text/plain:
                  example: "Event not found"
            500:
              description: "Internal server error"
              body:
                text/plain:
                  example: "Internal server error"
  /credentials-existence:
    get:
      description: Returns single property 'credentialsExist' with true, if user has local password
      queryParameters:
        userId:
          description: "User id"
          pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[1-5][a-fA-F0-9]{3}-[89abAB][a-fA-F0-9]{3}-[a-fA-F0-9]{12}$"
          required: true
      responses:
        200:
          body:
            application/json:
              schema: credentialsExistence
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error"