Permissions

/perms

/perms/users get post

get

Get a list of users (Okapi only, not on Eureka)

post

Add a new user (Okapi only, not on Eureka)

Get a list of users (Okapi only, not on Eureka)

Request
Response

Query Parameters

totalRecords: (string - default: auto - pattern: exact|estimated|none|auto)
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
```
none
```
offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
```
10
```
length: (integer - default: 10 - minimum: 1 - maximum: 2147483647)
The maximum number of results to return. Deprecated: use limit
Example:
```
10
```
start: (integer - default: 1 - minimum: 1 - maximum: 2147483647)
The starting index in a list of results starting from 1. Deprecated: use offset
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#",
  "type": "object",
  "description": "A collection of permission users",
  "properties": {
    "permissionUsers": {
      "description": "A list of permission users",
      "type": "array",
      "id": "permissionUsersListObject",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "A user that owns zero or more permissions",
        "properties": {
          "id": {
            "description": "The primary key (UUID) of this permissionUser record",
            "type": "string"
          },
          "userId": {
            "description": "A foreign key to the id field (UUID) of the user record in the users module",
            "type": "string"
          },
          "permissions": {
            "description": "A list of permission names owned by this user",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "description": "System level change metadata",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "metadata.schema",
            "title": "Metadata Schema",
            "properties": {
              "createdDate": {
                "description": "Date and time when the record was created",
                "type": "string",
                "format": "date-time"
              },
              "createdByUserId": {
                "description": "ID of the user who created the record (when available)",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "createdByUsername": {
                "description": "Username of the user who created the record (when available)",
                "type": "string"
              },
              "updatedDate": {
                "description": "Date and time when the record was last updated",
                "type": "string",
                "format": "date-time"
              },
              "updatedByUserId": {
                "description": "ID of the user who last updated the record (when available)",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "updatedByUsername": {
                "description": "Username of the user who last updated the record (when available)",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "createdDate"
            ]
          }
        },
        "required": [
          "userId"
        ],
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The total number of users in the result set",
      "type": "integer"
    }
  },
  "required": [
    "permissionUsers",
    "totalRecords"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

Add a new user (Okapi only, not on Eureka)

Request
Response

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

HTTP status code 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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

/perms/users/{id} get put delete

get

Get a permission user (Okapi only, not on Eureka)

put

Modify an existing user (Okapi only, not on Eureka)

delete

Remove a user (Okapi only, not on Eureka)

Get a permission user (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Query Parameters

indexField: (string)
Specify a field other than 'id' to look up the permission user by
Example:
```
userId
```

HTTP status code 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

User not found

Body

Media type: text/plain

Type: any

Example:

User does not exist

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

Modify an existing user (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

HTTP status code 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The primary key (UUID) of this permissionUser record",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key to the id field (UUID) of the user record in the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "required": [
    "userId"
  ],
  "additionalProperties": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

User not found

Body

Media type: text/plain

Type: any

Example:

User not found

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

Remove a user (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Query Parameters

indexField: (string)
Specify a field other than 'id' to look up the permission user by
Example:
```
userId
```

HTTP status code 204

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

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

/perms/users/{id}/permissions get post

get

Get permissions that a user has (Okapi only, not on Eureka)

post

Add a permission to a user (Okapi only, not on Eureka)

Get permissions that a user has (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Query Parameters

expanded: (string)
Recursively return all subpermissions
Example:
```
true
```
full: (string)
Return full permission objects, as opposed to just permission names
Example:
```
true
```
indexField: (string)
Specify a field other than 'id' to look up the permission user by
Example:
```
userId
```

HTTP status code 200

An object of returned permissions

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A list of only permission names",
  "properties": {
    "permissionNames": {
      "description": "A list of permission names",
      "type": "array",
      "id": "permissionNameListObject"
    },
    "totalRecords": {
      "description": "The total number of results in the set",
      "type": "integer"
    }
  },
  "required": [
    "permissionNames",
    "totalRecords"
  ]
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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

Add a permission to a user (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Query Parameters

indexField: (string)
Specify a field other than 'id' to look up the permission user by
Example:
```
userId
```

Body

Media type: application/json

Type: json

Content:

{
  "title": "Permissions Name Schema",
  "type": "object",
  "description": "An object only representing the name of a permission",
  "properties": {
    "permissionName": {
      "description": "The unique permission name",
      "type": "string"
    }
  }
}

HTTP status code 200

The added permission

Body

Media type: application/json

Type: json

Content:

{
  "title": "Permissions Name Schema",
  "type": "object",
  "description": "An object only representing the name of a permission",
  "properties": {
    "permissionName": {
      "description": "The unique permission name",
      "type": "string"
    }
  }
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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

/perms/users/{id}/permissions/{permissionname} delete

delete

Remove a permission from a user (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)
permissionname: required(string)

Query Parameters

indexField: (string)
Specify a field other than 'id' to look up the permission user by
Example:
```
userId
```

HTTP status code 204

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

HTTP status code 404

Permission not found in user

Body

Media type: text/plain

Type: any

Example:

Permission not found in user

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

/perms/permissions get post

get

Get a list of existing permissions (Okapi only, not on Eureka)

post

Add a new permission (Okapi only, not on Eureka)

Get a list of existing permissions (Okapi only, not on Eureka)

Request
Response

Query Parameters

expandSubs: (string)
Return one level of subpermissions as objects if true. If false or omitted, expanded will be considered.
Example:
```
true
```
expanded: (string)
Recursively return all subpermissions as strings if true. Is only considered if expandSubs is false or omitted.
Example:
```
true
```
includeDummy: (string)
Return placeholder 'dummy' permissions
Example:
```
true
```
totalRecords: (string - default: auto - pattern: exact|estimated|none|auto)
How to calculate the totalRecords property. "exact" for the correct number, "estimated" for an estimation, "auto" to automatically select "exact" or "estimated", "none" for suppressing the totalRecords property. For details see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
```
none
```
offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
Skip over a number of elements by specifying an offset value for the query
Example:
```
0
```
limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
Limit the number of elements returned in the response. Using limit=0 will return totalRecords with the exact value. For details about totalRecords see https://github.com/folio-org/raml-module-builder#estimated-totalrecords
Example:
```
10
```
length: (integer - default: 10 - minimum: 1 - maximum: 2147483647)
The maximum number of results to return. Deprecated: use limit
Example:
```
10
```
start: (integer - default: 1 - minimum: 1 - maximum: 2147483647)
The starting index in a list of results starting from 1. Deprecated: use offset
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#",
  "type": "object",
  "description": "A list of permissions",
  "properties": {
    "permissions": {
      "description": "A list of individual permissions",
      "type": "array",
      "id": "permissionsListObject",
      "items": {
        "type": "object",
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Permissions Definition Schema",
        "description": "A Folio permission",
        "properties": {
          "permissionName": {
            "description": "The unique name of the permission",
            "type": "string"
          },
          "displayName": {
            "description": "The human-readable name of the permission",
            "type": "string"
          },
          "id": {
            "description": "The globally unique (UUID) identifier for the permission",
            "type": "string"
          },
          "description": {
            "description": "A description of the permission",
            "type": "string"
          },
          "tags": {
            "description": "A list of tags for searching",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subPermissions": {
            "description": "A list of child permissions granted by this permission",
            "type": "array"
          },
          "childOf": {
            "description": "A list of permissions that 'own' this permission",
            "type": "array"
          },
          "grantedTo": {
            "description": "A list of permission users to whom this permission has been granted",
            "type": "array"
          },
          "mutable": {
            "description": "Whether or not this permission changes at runtime",
            "type": "boolean"
          },
          "visible": {
            "description": "Whether or not this permission is visible to users",
            "type": "boolean"
          },
          "dummy": {
            "description": "Is this a temporary dummy permission",
            "type": "boolean"
          },
          "deprecated": {
            "description": "Indicates whether this permissions has been marked for deletion (soft deleted)",
            "type": "boolean",
            "default": false
          },
          "moduleName": {
            "description": "The name of the module (not including version) that defined this permission",
            "type": "string",
            "readOnly": true
          },
          "moduleVersion": {
            "description": "The version of the module that defined this permission",
            "type": "string",
            "readOnly": true
          },
          "metadata": {
            "description": "System modification metadata",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "id": "metadata.schema",
            "title": "Metadata Schema",
            "properties": {
              "createdDate": {
                "description": "Date and time when the record was created",
                "type": "string",
                "format": "date-time"
              },
              "createdByUserId": {
                "description": "ID of the user who created the record (when available)",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "createdByUsername": {
                "description": "Username of the user who created the record (when available)",
                "type": "string"
              },
              "updatedDate": {
                "description": "Date and time when the record was last updated",
                "type": "string",
                "format": "date-time"
              },
              "updatedByUserId": {
                "description": "ID of the user who last updated the record (when available)",
                "type": "string",
                "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
              },
              "updatedByUsername": {
                "description": "Username of the user who last updated the record (when available)",
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "createdDate"
            ]
          }
        },
        "additionalProperties": false
      }
    },
    "totalRecords": {
      "description": "The total number of permissions in the result set",
      "type": "integer"
    }
  },
  "required": [
    "permissions",
    "totalRecords"
  ]
}

HTTP status code 400

Bad request

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

Add a new permission (Okapi only, not on Eureka)

Request
Response

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "additionalProperties": false
}

HTTP status code 201

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "additionalProperties": false
}

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

/perms/permissions/{id} get put delete

get

Get an existing permission by id (Okapi only, not on Eureka)

put

Modify an existing permission (Okapi only, not on Eureka)

delete

Remove a permission (Okapi only, not on Eureka)

Get an existing permission by id (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

HTTP status code 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "type": "object",
  "description": "A Folio permission",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "The globally unique (UUID) identifier for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for searching",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array"
    },
    "childOf": {
      "description": "A list of permissions that 'own' this permission",
      "type": "array"
    },
    "grantedTo": {
      "description": "A list of permission users to whom this permission has been granted",
      "type": "array"
    },
    "mutable": {
      "description": "Whether or not this permission changes at runtime",
      "type": "boolean"
    },
    "visible": {
      "description": "Whether or not this permission is visible to users",
      "type": "boolean"
    },
    "dummy": {
      "description": "Is this a temporary dummy permission",
      "type": "boolean"
    },
    "deprecated": {
      "description": "Indicates whether this permissions has been marked for deletion (soft deleted)",
      "type": "boolean",
      "default": false
    },
    "moduleName": {
      "description": "The name of the module (not including version) that defined this permission",
      "type": "string",
      "readOnly": true
    },
    "moduleVersion": {
      "description": "The version of the module that defined this permission",
      "type": "string",
      "readOnly": true
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "additionalProperties": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission not found

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

Modify an existing permission (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "additionalProperties": false
}

HTTP status code 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Permissions Definition Schema",
  "description": "Information for POSTing a new permission",
  "type": "object",
  "properties": {
    "permissionName": {
      "description": "The unique name of the permission",
      "type": "string"
    },
    "displayName": {
      "description": "The human-readable name of the permission",
      "type": "string"
    },
    "id": {
      "description": "A globally unique id for the permission",
      "type": "string"
    },
    "description": {
      "description": "A description of the permission",
      "type": "string"
    },
    "tags": {
      "description": "A list of tags for retrieval of the permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "subPermissions": {
      "description": "A list of child permissions granted by this permission",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mutable": {
      "description": "Whether or not this permission can change at runtime.  Since v5.13.0 this property is ignored.  All permissions created or modified via this API are always mutable",
      "type": "boolean"
    },
    "visible": {
      "description": "Should this permission be hidden from users",
      "type": "boolean"
    },
    "metadata": {
      "description": "System modification metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "id": "metadata.schema",
      "title": "Metadata Schema",
      "properties": {
        "createdDate": {
          "description": "Date and time when the record was created",
          "type": "string",
          "format": "date-time"
        },
        "createdByUserId": {
          "description": "ID of the user who created the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "createdByUsername": {
          "description": "Username of the user who created the record (when available)",
          "type": "string"
        },
        "updatedDate": {
          "description": "Date and time when the record was last updated",
          "type": "string",
          "format": "date-time"
        },
        "updatedByUserId": {
          "description": "ID of the user who last updated the record (when available)",
          "type": "string",
          "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
        },
        "updatedByUsername": {
          "description": "Username of the user who last updated the record (when available)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "createdDate"
      ]
    }
  },
  "additionalProperties": false
}

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

HTTP status code 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission not found

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

Remove a permission (Okapi only, not on Eureka)

Request
Response

URI Parameters

id: required(string)

HTTP status code 204

HTTP status code 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

HTTP status code 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission not found

HTTP status code 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

/perms/purge-deprecated post

post

purge deprecated permissions (Okapi only, not on Eureka)

Response

HTTP status code 200

A list of permission names purged

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A list of only permission names",
  "properties": {
    "permissionNames": {
      "description": "A list of permission names",
      "type": "array",
      "id": "permissionNameListObject"
    },
    "totalRecords": {
      "description": "The total number of results in the set",
      "type": "integer"
    }
  },
  "required": [
    "permissionNames",
    "totalRecords"
  ]
}

HTTP status code 400

Bad request

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

Permissions version v5.5

mod-permissions API (Okapi only, not on Eureka)

/perms

Permissions version v5.5

mod-permissions API (Okapi only, not on Eureka)

/perms

/perms/users get post

get /perms/users

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 500

Body

post /perms/users

Body

HTTP status code 201

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 422

Body

HTTP status code 500

Body

/perms/users/{id} get put delete

get /perms/users/{id}

URI Parameters

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 404

Body

HTTP status code 500

Body

put /perms/users/{id}

URI Parameters

Body

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 404

Body

HTTP status code 422

Body

HTTP status code 500

Body

delete /perms/users/{id}

URI Parameters

Query Parameters

HTTP status code 204

HTTP status code 400

Body

HTTP status code 404

Body

HTTP status code 500

Body

/perms/users/{id}/permissions get post

get /perms/users/{id}/permissions

URI Parameters

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 403

Body

HTTP status code 404

Body

HTTP status code 500

Body

post /perms/users/{id}/permissions