Login API documentation version v1.1
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#",
"type": "object",
"properties": {
"errors": {
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$ref": "error.schema"
}
},
"total_records": {
"type": "integer"
}
}
}
HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorSelf-update existing credentials
post /authn/update
Self-update existing credentials
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#",
"type": "object",
"properties": {
"errors": {
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$ref": "error.schema"
}
},
"total_records": {
"type": "integer"
}
}
}
HTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorGet a list of user credentials
Add a new login to the system
get /authn/credentials
Get a list of user credentials
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).
- sortBy: (string)
A comma-separated list of fieldnames to sort by
- query: (string)
A query string to filter users based on matching criteria in fields.
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Credentials List Object",
"type": "object",
"description": "Response entity describing a list of user data, as well as their number in db",
"properties": {
"credentials": {
"type": "array",
"description": "List of user credentials",
"id": "credentialsListObject",
"items": {
"type": "object",
"$ref": "credentials.json"
}
},
"totalRecords": {
"type": "integer"
}
},
"required": [
"credentials",
"totalRecords"
]
}
HTTP status code 400
Bad request
Body
Media type: text/plain
Type: any
Example:
Bad requestHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorpost /authn/credentials
Add a new login to the system
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
Body
Media type: application/json
Type: json
Content:
{
"title": "Credentials Schema",
"type": "object",
"description": "An entity that describes the basic user login data",
"properties": {
"id": {
"description": "Unique credentials id",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"hash": {
"description": "The generated hash that participates in decoding the password",
"type": "string"
},
"salt": {
"description": "The generated salt that is involved in decrypting the password",
"type": "string"
},
"metadata": {
"type": "object",
"$ref": "raml-util/schemas/metadata.schema"
}
}
}
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#",
"type": "object",
"properties": {
"errors": {
"id": "errors",
"type": "array",
"items": {
"type": "object",
"$ref": "error.schema"
}
},
"total_records": {
"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 errorGet login credentials for a single user
Modify a user's login credentials
Remove a user's login credentials from the system
get /authn/credentials/{id}
Get login credentials for a single user
URI Parameters
- id: required (string)
HTTP status code 200
Body
Media type: application/json
Type: json
Content:
{
"title": "Credentials Schema",
"type": "object",
"description": "An entity that describes the basic user login data",
"properties": {
"id": {
"description": "Unique credentials id",
"type": "string"
},
"userId": {
"description": "Unique user id",
"type": "string"
},
"hash": {
"description": "The generated hash that participates in decoding the password",
"type": "string"
},
"salt": {
"description": "The generated salt that is involved in decrypting the password",
"type": "string"
},
"metadata": {
"type": "object",
"$ref": "raml-util/schemas/metadata.schema"
}
}
}
HTTP status code 404
User not found
Body
Media type: text/plain
Type: any
Example:
User not foundHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errorput /authn/credentials/{id}
Modify a user's login credentials
URI Parameters
- id: 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 200
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 404
User not found
Body
Media type: text/plain
Type: any
Example:
User not foundHTTP status code 500
Internal server error
Body
Media type: text/plain
Type: any
Example:
Internal server errordelete /authn/credentials/{id}
Remove a user's login credentials from the system
Validate 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"
}
},
"required": [
"password"
]
}
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