Login version v7.0

http://github.com/org/folio/mod-auth/login_module

mod-login API

This module provides a username/password based login mechanism for FOLIO credentials

/authn

get

get

Get login attempts for a single user

Get login attempts for a single user

URI Parameters

  • id: required(string)

HTTP status code 200

Body

Media type: application/json

HTTP status code 404

User not found

Body

Media type: text/plain

Type: any

Example:

User not found

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Deprecated. Please use login-with-expiry instead. Will be removed in a future release. Get a new login token without an expiration (legacy endpoint)

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: required(string)
  • X-Forwarded-For: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "title": "Login Credentials Schema",
  "type": "object",
  "description": "An entity that describes the basic credentials for a user to log on to the system",
  "properties": {
    "username": {
      "description": "Username in the system, case insensitive",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "User password",
      "type": "string"
    },
    "tenant": {
      "description": "Tenant; parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

HTTP status code 201

Headers

  • x-okapi-token: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Object returned on successful login",
  "type": "object",
  "properties": {
    "okapiToken": {
      "description": "session token (X-Okapi-Token format)",
      "type": "string"
    },
    "refreshToken": {
      "description": "refresh token",
      "type": "string"
    }
  },
  "required": [
    "okapiToken"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 404

Not found

Body

Media type: text/plain

Type: any

Example:

Not found

HTTP status code 422

Unprocessable Entity

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Get an expiring refresh and access token

Get an expiring refresh and access token

Headers

  • User-Agent: required(string)
  • X-Forwarded-For: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "title": "Login Credentials Schema",
  "type": "object",
  "description": "An entity that describes the basic credentials for a user to log on to the system",
  "properties": {
    "username": {
      "description": "Username in the system, case insensitive",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "User password",
      "type": "string"
    },
    "tenant": {
      "description": "Tenant; parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

HTTP status code 201

Headers

  • Set-Cookie: required(string)

    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

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Object returned on successful login or on token refresh",
  "type": "object",
  "properties": {
    "accessTokenExpiration": {
      "description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
      "type": "string"
    },
    "refreshTokenExpiration": {
      "description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
      "type": "string"
    }
  },
  "required": [
    "accessTokenExpiration",
    "refreshTokenExpiration"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 404

Not found

Body

Media type: text/plain

Type: any

Example:

Not found

HTTP status code 422

Unprocessable Entity

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Get a new refresh and access token

Get a new refresh and access token

Headers

  • Cookie: required(string)

    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

HTTP status code 201

Headers

  • Set-Cookie: required(string)

    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

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Object returned on successful login or on token refresh",
  "type": "object",
  "properties": {
    "accessTokenExpiration": {
      "description": "The time in UTC after which the access token will be considered expired. Time format is ISO 8601.",
      "type": "string"
    },
    "refreshTokenExpiration": {
      "description": "The time in UTC after which the refresh token will be considered expired. Time format is ISO 8601.",
      "type": "string"
    }
  },
  "required": [
    "accessTokenExpiration",
    "refreshTokenExpiration"
  ]
}

HTTP status code 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

HTTP status code 422

Unprocessable entity. mod-authtoken has returned a 400 level response.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Logs the user out on their current device. The access token cookie and the refresh token cookie are removed, and the refresh token is invalidated. The access token cannot be invalidated and remains valid until its exiration time; this is by design because the access token is stateless.

Logs the user out on their current device. The access token cookie and the refresh token cookie are removed, and the refresh token is invalidated. The access token cannot be invalidated and remains valid until its exiration time; this is by design because the access token is stateless.

Headers

  • Cookie: required(string)

    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

HTTP status code 204

HTTP status code 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

HTTP status code 422

Unprocessable entity. mod-authtoken has returned a 400 level response.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Logs the user out on all of their devices

Logs the user out on all of their devices

HTTP status code 204

HTTP status code 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

HTTP status code 422

Unprocessable entity. mod-authtoken has returned a 400 level response.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Self-update existing credentials. N.B. A non-empty password must be provided.

Self-update existing credentials. N.B. A non-empty password must be provided.

Headers

  • User-Agent: required(string)
  • X-Forwarded-For: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "title": "Update Credentials Schema",
  "type": "object",
  "description": "An entity that describes the necessary data to update a user password",
  "properties": {
    "username": {
      "description": "username",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "The current password of the user who will be replaced by the new one",
      "type": "string"
    },
    "newPassword": {
      "description": "New user password",
      "type": "string"
    }
  }
}

HTTP status code 204

Successful update

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 401

Unauthorized

Body

Media type: text/plain

Type: any

Example:

Unauthorized

HTTP status code 422

Unprocessable Entity

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post delete

post

Add a new login to the system. N.B. A non-empty password must be provided.

delete

Remove a user's login credentials from the system

Add a new login to the system. N.B. A non-empty password must be provided.

Body

Media type: application/json

Type: json

Content:

{
  "title": "Login Credentials Schema",
  "type": "object",
  "description": "An entity that describes the basic credentials for a user to log on to the system",
  "properties": {
    "username": {
      "description": "Username in the system, case insensitive",
      "type": "string"
    },
    "userId": {
      "description": "Unique user id",
      "type": "string"
    },
    "password": {
      "description": "User password",
      "type": "string"
    },
    "tenant": {
      "description": "Tenant; parameter for resolving duplicated usernames across tenants.",
      "type": "string"
    }
  }
}

HTTP status code 201

Success

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "errors.schema",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "error.schema",
        "description": "An error",
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message text"
          },
          "type": {
            "type": "string",
            "description": "Error message type"
          },
          "code": {
            "type": "string",
            "description": "Error message code"
          },
          "parameters": {
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "parameters.schema",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Validate if password has been used before.

Validate if password has been used before.

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Object with password property",
  "type": "object",
  "properties": {
    "password": {
      "type": "string",
      "description": "Password"
    },
    "userId": {
      "type": "string",
      "description": "User Id"
    }
  },
  "required": [
    "password",
    "userId"
  ]
}

HTTP status code 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "result",
  "type": "object",
  "properties": {
    "result": {
      "type": "string",
      "description": "'invalid' if the password is in the user's password history, 'valid' otherwise"
    }
  },
  "required": [
    "result"
  ]
}

Example:

{
  "result": "invalid"
}

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Resets password for user in record and deletes action record

Resets password for user in record and deletes action record

Headers

  • User-Agent: required(string)
  • X-Forwarded-For: required(string)

Body

Media type: application/json

HTTP status code 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Response entity to reset the password",
  "type": "object",
  "properties": {
    "isNewPassword": {
      "description": "true if a password has been set the first time for this user, false if the previous password has been moved into the user's password history",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

HTTP status code 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

post

post

Saves action to storage

Saves action to storage

Body

Media type: application/json

HTTP status code 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Response entity to create a new password change action",
  "type": "object",
  "properties": {
    "passwordExists": {
      "description": "true if a password is stored for the user, false if no password (or even no credential entry) is stored for the user",
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

HTTP status code 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

get

get

Retrieves action record by id

Retrieves action record by id

URI Parameters

  • actionId: required(string)

HTTP status code 200

Body

Media type: application/json

HTTP status code 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

HTTP status code 404

Body

Media type: text/plain

Type: any

Example:

Not Found

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

get post

get

Returns a list of events retrieved from storage

post

Saves received event into the storage

Saves received event into the storage

Body

Media type: application/json

HTTP status code 201

Body

Media type: application/json

HTTP status code 204

Body

Media type: text/plain

Type: any

Example:

No Content

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

delete

delete

Removes events by filter

Removes events by filter

URI Parameters

  • id: required(string)

HTTP status code 200

Body

Media type: application/json

HTTP status code 204

Body

Media type: text/plain

Type: any

Example:

No Content

HTTP status code 404

Event not found

Body

Media type: text/plain

Type: any

Example:

Event not found

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

get

get

Returns single property 'credentialsExist' with true, if user has local password