Permissions (v1)

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

Table of contents

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
  • length: (integer - default: 10 - minimum: 1 - maximum: 2147483647)

    The maximum number of results to return.

    Example:

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

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

  • sortBy: (string)

    A comma-separated list of fieldnames to sort by

  • query: (string)

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

  • hasPermissions: (string)

    A list of permissions that any returned users must possess.

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 globally unique (UUIDO) id of the user",
            "type": "string"
          },
          "userId": {
            "description": "A foreign key (UUID) from the users module",
            "type": "string"
          },
          "permissions": {
            "description": "A list of permission names owned by this user",
            "type": "array"
          },
          "metadata": {
            "description": "System level change metadata",
            "type": "object",
            "$schema": "http://json-schema.org/draft-04/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 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 globally unique (UUIDO) id of the user",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key (UUID) from the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array"
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/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#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The globally unique (UUIDO) id of the user",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key (UUID) from the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array"
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/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#",
  "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#",
        "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": {
            "type": "object",
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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 globally unique (UUIDO) id of the user",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key (UUID) from the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array"
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/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

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 globally unique (UUIDO) id of the user",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key (UUID) from the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array"
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/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#",
  "type": "object",
  "description": "A user that owns zero or more permissions",
  "properties": {
    "id": {
      "description": "The globally unique (UUIDO) id of the user",
      "type": "string"
    },
    "userId": {
      "description": "A foreign key (UUID) from the users module",
      "type": "string"
    },
    "permissions": {
      "description": "A list of permission names owned by this user",
      "type": "array"
    },
    "metadata": {
      "description": "System level change metadata",
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/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

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#",
  "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#",
        "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": {
            "type": "object",
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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)

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 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/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#",
        "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": {
            "type": "object",
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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
  • length: (integer - default: 10 - minimum: 1 - maximum: 2147483647)

    The maximum number of results to return.

    Example:

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

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

  • sortBy: (string)

    A comma-separated list of fieldnames to sort by

  • query: (string)

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

  • memberOf: (string)

    A list of permission names that any returned permission must be a sub-permission of.

  • ownedBy: (string)

    A list of user names that any returned permissions must belong to.

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#",
            "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#",
      "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#",
      "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#",
  "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#",
        "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": {
            "type": "object",
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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#",
      "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#",
      "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#",
      "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 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/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#",
        "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": {
            "type": "object",
            "description": "Error message parameters",
            "$schema": "http://json-schema.org/draft-04/schema#",
            "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