Login (v7.0)

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

Table of contents

mod-login API

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

/authn

GET /authn/loginAttempts/{id}

Get login attempts for a single user

GET /authn/loginAttempts/{id}
URI Parameters
  • id: required (string)

Response 200

Body

Media type: application/json

Response 404

User not found

Body

Media type: text/plain

Type: any

Example:

User not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/login

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

POST /authn/login
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"
    }
  }
}

Response 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"
  ]
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 404

Not found

Body

Media type: text/plain

Type: any

Example:

Not found

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/login-with-expiry

Get an expiring refresh and access token

POST /authn/login-with-expiry
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"
    }
  }
}

Response 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"
  ]
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 404

Not found

Body

Media type: text/plain

Type: any

Example:

Not found

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/refresh

Get a new refresh and access token

POST /authn/refresh
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

Response 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"
  ]
}

Response 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/logout

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.

POST /authn/logout
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

Response 204

Response 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/logout-all

Logs the user out on all of their devices

POST /authn/logout-all

Response 204

Response 400

Bad request

Body

Media type: application/json

Type: any

Example:

Bad request

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/update

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

POST /authn/update
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"
    }
  }
}

Response 204

Successful update

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 401

Unauthorized

Body

Media type: text/plain

Type: any

Example:

Unauthorized

Response 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"
    }
  }
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/credentials

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

POST /authn/credentials
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"
    }
  }
}

Response 201

Success

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 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"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

DELETE /authn/credentials

Remove a user's login credentials from the system

DELETE /authn/credentials
Query Parameters
  • userId: required (string - 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}$)

    User Id

Response 204

Success

Response 404

User not found

Body

Media type: text/plain

Type: any

Example:

User not found

Response 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"
        }
      ]
    }
  ]
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/password/repeatable

Validate if password has been used before.

POST /authn/password/repeatable
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"
  ]
}

Response 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"
}

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/reset-password

Resets password for user in record and deletes action record

POST /authn/reset-password
Headers
  • User-Agent: required (string)
  • X-Forwarded-For: required (string)
Body

Media type: application/json

Response 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
}

Response 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/password-reset-action

Saves action to storage

POST /authn/password-reset-action
Body

Media type: application/json

Response 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
}

Response 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /authn/password-reset-action/{actionId}

Retrieves action record by id

GET /authn/password-reset-action/{actionId}
URI Parameters
  • actionId: required (string)

Response 200

Body

Media type: application/json

Response 400

Body

Media type: text/plain

Type: any

Example:

Bad Request

Response 404

Body

Media type: text/plain

Type: any

Example:

Not Found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /authn/log/events

Returns a list of events retrieved from storage

GET /authn/log/events
Query Parameters
  • length: (integer - default: 10 - minimum: 1 - maximum: 2147483647)

    The maximum number of results to return.

    Example:

    10
  • start: (integer - default: 1 - minimum: 1 - maximum: 2147483647)

    The starting index in a list of results (starts at one).

  • query: (string)

    A query string to filter users based on matching criteria in fields.

Response 200

Body

Media type: application/json

Response 204

Body

Media type: text/plain

Type: any

Example:

No Content

Response 404

Event not found

Body

Media type: text/plain

Type: any

Example:

Event not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /authn/log/events

Saves received event into the storage

POST /authn/log/events
Body

Media type: application/json

Response 201

Body

Media type: application/json

Response 204

Body

Media type: text/plain

Type: any

Example:

No Content

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

DELETE /authn/log/events/{id}

Removes events by filter

DELETE /authn/log/events/{id}
URI Parameters
  • id: required (string)

Response 200

Body

Media type: application/json

Response 204

Body

Media type: text/plain

Type: any

Example:

No Content

Response 404

Event not found

Body

Media type: text/plain

Type: any

Example:

Event not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /authn/credentials-existence

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

GET /authn/credentials-existence
Query Parameters
  • userId: required (string - 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}$)

    User id

Response 200

Body

Media type: application/json

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error