Login API documentation 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 login attempts for a single user
get /authn/loginAttempts/{id}
Get login attempts for a single user
Get a new login token
post /authn/login
Get a new login 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",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
}
}
}HTTP status code 201
Headers
- x-okapi-token: required(string)
- refreshtoken: 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",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
}
}
}HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP 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 errorSelf-update existing credentials. N.B. A non-empty password must be provided.
post /authn/update
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 requestHTTP status code 401
Unauthorized
Body
Media type: text/plain
Type: any
Example:
UnauthorizedHTTP 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 errorAdd a new login to the system. N.B. A non-empty password must be provided.
Remove a user's login credentials from the system
post /authn/credentials
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",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"password": {
"description": "User password",
"type": "string"
}
}
}HTTP status code 201
Success
HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP 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 errordelete /authn/credentials
Remove a user's login credentials from the system
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
HTTP status code 204
Success
HTTP status code 404
User not found
Body
Media type: text/plain
Type: any
Example:
User not foundHTTP 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 errorValidate password for repeatability
post /authn/password/repeatable
Validate password for repeatability
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": "result"
}
},
"required": [
"result"
]
}HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorResets password for user in record and deletes action record
post /authn/reset-password
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
Saves action to storage
post /authn/password-reset-action
Saves action to storage
Retrieves action record by id
get /authn/password-reset-action/{actionId}
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 RequestHTTP status code 404
Body
Media type: text/plain
Type: any
Example:
Not FoundHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorReturns a list of events retrieved from storage
Saves received event into the storage
get /authn/log/events
Returns a list of events retrieved from storage
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.
HTTP status code 200
Body
Media type: application/json
HTTP status code 204
Body
Media type: text/plain
Type: any
Example:
No ContentHTTP status code 404
Event not found
Body
Media type: text/plain
Type: any
Example:
Event not foundHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorpost /authn/log/events
Saves received event into the storage
Removes events by filter
delete /authn/log/events/{id}
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 ContentHTTP status code 404
Event not found
Body
Media type: text/plain
Type: any
Example:
Event not foundHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorReturns single property 'credentialsExist' with true, if user has local password
get /authn/credentials-existence
Returns single property 'credentialsExist' with true, if user has local password
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