+ "description": "---\n# Introduction\npfSense API is a fast, safe, REST API package for pfSense firewalls. This works by leveraging the same PHP functions and processes used \nby pfSense's webConfigurator into API endpoints to create, read, update and delete pfSense configurations. All API \nendpoints enforce input validation to prevent invalid configurations from being made. Configurations made via API are \nproperly written to the master XML configuration and the correct backend configurations are made preventing the need for\n a reboot. All this results in the fastest, safest, and easiest way to automate pfSense!\n\n# Requirements\n- pfSense 2.4.4 or later is supported\n- pfSense API requires a local user account in pfSense. The same permissions required to make configurations in the \nwebConfigurator are required to make calls to the API endpoints\n- While not an enforced requirement, it is STRONGLY recommended that you configure pfSense to use HTTPS instead of HTTP. This ensures that login credentials and/or API tokens remain secure in-transit\n\n# Installation\nTo install pfSense API, simply run the following command from the pfSense shell:<br>\n```\npkg add https://github.com/jaredhendrickson13/pfsense-api/releases/download/v0.0.4/pfSense-2-4-pkg-API-0.0_4.txz && /etc/rc.restart_webgui\n```\n<br>\n\nTo uninstall, run the following command:<br>\n```\npkg delete pfSense-pkg-API\n```\n<br>\n\n### Notes: \n- In order for pfSense to apply some required web server changes, it is required to restart the webConfigurator after installing the package\n- If you do not have shell access to pfSense, you can still install via the webConfigurator by navigating to \n'Diagnostics > Command Prompt' and enter the commands there\n\n# UI Settings & Documentation\nAfter installation, you will be able to access the API user interface pages within the pfSense webConfigurator. These will be found under System > API. The settings tab will allow you change various API settings such as enabled API interfaces, authentication modes, and more. Additionally, the documentation tab will give you access to an embedded documentation tool that makes it easy to view the full API documentation with context to your pfSense instance.\n\n### Notes: \n- Users must hold the `page-all` or `page-system-api` privileges to access the API page within the webConfigurator\n\n# Authentication\nBy default, pfSense API uses the same credentials as the webConfigurator. This behavior allows you to configure pfSense \nfrom the API out of the box, and user passwords may be changed from the API to immediately add additional security if \nneeded. After installation, you can navigate to System > API in the pfSense webConfigurator to configure API\nauthentication.\n\nTo authenticate your API call, follow the instructions for your configured authentication mode:\n\n- Local Database (default) : Uses the same credentials as the pfSense webConfigurator. To authenticate API calls, simply\nadd a `client-id` value containing your username and a `client-token` value containing your password to your payload. For \nexample `{\"client-id\": \"admin\", \"client-token\": \"pfsense\"}`\n\n- JWT : Requires a bearer token to be included in the `Authorization` header of your request. To receive a bearer token,\nyou may make a POST request to /api/v1/access_token/ and include a `client-id` value containing your pfSense username \nand a `client-token` value containing your pfSense password to your payload. For example \n`{\"client-id\": \"admin\", \"client-token\": \"pfsense\"}`. Once you have your bearer token, you can authenticate your API\ncall by adding it to the request's authorization header. (e.g. `Authorization: Bearer xxxxxxxx.xxxxxxxxx.xxxxxxxx`)\n\n- API Token : Uses standalone tokens generated via the UI. These are better suited to distribute to systems as they are\nrevocable and will only allow API authentication and not UI or SSH authentication (like the local database credentials). \nTo generate or revoke credentials, navigate to System > API within the UI and ensure the Authentication Mode is set to\nAPI token. Then you should have the options to configure API Token generation, generate new tokens, and revoke existing\ntokens. Once you have your API token, you may authenticate your API call by adding a `client-id` value containing your\nAPI token client ID and a `client-token` value containing your API token client token to your payload.\n(e.g. `{\"client-id\": \"cccdj-311s\", \"client-token\": \"42jkjl-k234jlk1b38123kj3kjl-ffwzzuilaei\"}`\n\n# Authorization\npfSense API uses the same privielges as the pfSense webConfigurator. The required privileges for each endpoint are stated within the API documentation.\n\n# Response Codes\n`200 (OK)` : API call succeeded<br>\n`400 (Bad Request)` : An error was found within your requested parameters<br>\n`401 (Unauthorized)` : API client has not completed authentication or authorization successfully<br>\n`403 (Forbidden)` : The API endpoint has refused your call. Commonly due to your access settings found in `System > API`<br>\n`404 (Not found)` : Either the API endpoint or requested data was not found<br>\n`500 (Server error)` : The API endpoint encountered an unexpected error processing your API request<br>\n\n# Error Codes\nA full list of error codes can be found by navigating to /api/v1/system/api/errors/ after installation. This will return\n JSON data containing each error code and their corresponding error message. No authentication is required to view the \n error code library. This also makes API integration with third-party software easy as the API error codes and messages \n are always just an HTTP call away!\n\n# Queries\nFor endpoints supporting `GET` requests, you may query the return data to only return data you are looking for. To query data, you may add the data you are looking for to your payload. You may specify as many query parameters as you like to, in order to match the query, each parameter must match exactly. If no matches were found, the endpoint will return an empty array in the data field. \n<details>\n <summary>Show example</summary>\nFor example, say an API endpoint normally returns a response like this without a query:\n\n```json\n{\n \"status\":\"ok\",\n \"code\":200,\n \"return\":0,\n \"message\":\"Success\",\n \"data\": [\n {\"id\": 0, \"name\": \"Test\", \"type\": \"type1\"}, \n {\"id\": 1, \"name\": \"Other Test\", \"type\": \"type2\"},\n {\"id\": 2, \"name\": \"Another Test\", \"type\": \"type1\"}\n\n ]\n}\n```\n\nIf I wanted the endpoint to only return the objects that had their `type` set to `type1` I could add `{\"type\": \"type1\"}` to my payload. These would return something like this:\n\n```json\n{\n \"status\":\"ok\",\n \"code\":200,\n \"return\":0,\n \"message\":\"Success\",\n \"data\": [\n {\"id\": 0, \"name\": \"Test\", \"type\": \"type1\"}, \n {\"id\": 2, \"name\": \"Another Test\", \"type\": \"type1\"}\n ]\n}\n```\n</details>\n\n\n### Requirements for queries:\n- API call must be successful and return `0` in the `return` field.\n- Endpoints must return an array of objects in the data field (e.g. `[{\"id\": 0, \"name\": \"Test\"}, {\"id\": 1, \"name\": \"Other Test\"}]`).\n- At least two objects must be present within the array to support queries.\n- If an array is being used in a query, it must much the target data completely and exactly. There are no recursive queries.\n\n### Notes:\n- For those using the Local database or API token authentication types, `client-id` and `client-token` are excluded from queries\n\n# Rate limit\nThere is no limit to API calls at this time but is important to note that pfSense's XML configuration was not designed for quick simultaneous writes like a traditional database. It may be necessary to delay API calls in sequence to prevent unexpected behavior. Alternatively, you may limit the API to read-only mode to only allow endpoints with read (GET) access within the webConfigurator's System > API page.",
0 commit comments