Permissions (v5.5)

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

mod-permissions API
/perms

mod-permissions API

This module is responsible for managing and retrieving permissions in the FOLIO system

/perms

GET /perms/users

Get a list of users

GET /perms/users

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.

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /perms/users

Add a new user

POST /perms/users

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
}

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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

GET /perms/users/{id}

Get a permission user

GET /perms/users/{id}

URI Parameters

id: required (string)

Query Parameters

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

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

User not found

Body

Media type: text/plain

Type: any

Example:

User does not exist

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

PUT /perms/users/{id}

Modify an existing user

PUT /perms/users/{id}

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
}

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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

DELETE /perms/users/{id}

Remove a user

DELETE /perms/users/{id}

URI Parameters

id: required (string)

Query Parameters

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

Response 204

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

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

GET /perms/users/{id}/permissions

Get permissions that a user has

GET /perms/users/{id}/permissions

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
```

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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 /perms/users/{id}/permissions

Add a permission to a user

POST /perms/users/{id}/permissions

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

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

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 /perms/users/{id}/permissions/{permissionname}

Remove a permission from a user

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

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
```

Response 204

Response 400

Bad request

Body

Media type: text/plain

Type: any

Response 404

Permission not found in user

Body

Media type: text/plain

Type: any

Example:

Permission not found in user

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /perms/permissions

Get a list of existing permissions

GET /perms/permissions

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.

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

Response 400

Bad request

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 /perms/permissions

Add a new permission

POST /perms/permissions

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
}

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

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

GET /perms/permissions/{id}

Get an existing permission by id

GET /perms/permissions/{id}

URI Parameters

id: required (string)

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

PUT /perms/permissions/{id}

Modify an existing permission

PUT /perms/permissions/{id}

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
}

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

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 403

Access Denied

Body

Media type: text/plain

Type: any

Example:

Access Denied

Response 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission 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

DELETE /perms/permissions/{id}

Remove a permission

DELETE /perms/permissions/{id}

URI Parameters

id: required (string)

Response 204

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 404

Permission not found

Body

Media type: text/plain

Type: any

Example:

Permission not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /perms/purge-deprecated

purge deprecated permissions

POST /perms/purge-deprecated

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

Response 400

Bad request

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

Permissions (v5.5)

Table of contents

mod-permissions API

/perms

GET /perms/users

Query Parameters

Response 200

Response 400

Response 403

Response 500

POST /perms/users

Response 201

Response 400

Response 403

Response 422

Response 500

GET /perms/users/{id}

URI Parameters

Query Parameters

Response 200

Response 400

Response 403

Response 404

Response 500

PUT /perms/users/{id}

URI Parameters

Response 200

Response 400

Response 403

Response 404

Response 422

Response 500

DELETE /perms/users/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /perms/users/{id}/permissions

URI Parameters

Query Parameters

Response 200

Response 400

Response 403

Response 404

Response 500

POST /perms/users/{id}/permissions

URI Parameters

Query Parameters

Response 200

Response 400

Response 403

Response 422

Response 500

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

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

GET /perms/permissions

Query Parameters

Response 200

Response 400

Response 500

POST /perms/permissions

Response 201

Response 400

Response 422

Response 500

GET /perms/permissions/{id}

URI Parameters

Response 200

Response 400

Response 404

Response 500

PUT /perms/permissions/{id}

URI Parameters