|
40 | 40 | authentication. |
41 | 41 | To authenticate your API call, follow the instructions for your configured authentication mode: |
42 | 42 | <details> |
43 | | -<summary>Local Database (default)</summary |
| 43 | +<summary>Local Database (default)</summary> |
44 | 44 | Uses the same credentials as the pfSense webConfigurator. To authenticate API calls, simply add a `client-id` value containing your username and a `client-token` value containing your password to your payload. For example `{"client-id": "admin", "client-token": "pfsense"}` |
45 | 45 | </details> |
46 | 46 | <details> |
47 | | -<summary>JWT</summary |
| 47 | +<summary>JWT</summary> |
48 | 48 | Requires a bearer token to be included in the `Authorization` header of your request. To receive a bearer token, you may make a POST request to /api/v1/access_token/ and include a `client-id` value containing your pfSense username and a `client-token` value containing your pfSense password to your payload. For example `{"client-id": "admin", "client-token": "pfsense"}`. Once you have your bearer token, you can authenticate your APIcall by adding it to the request's authorization header. (e.g. `Authorization: Bearer xxxxxxxx.xxxxxxxxx.xxxxxxxx`) |
49 | 49 | </details> |
50 | 50 | <details> |
51 | | -<summary>API Token</summary |
| 51 | +<summary>API Token</summary> |
52 | 52 | Uses standalone tokens generated via the UI. These are better suited to distribute to systems as they are revocable and will only allow API authentication and not UI or SSH authentication (like the local database credentials). To generate or revoke credentials, navigate to System > API within the UI and ensure the Authentication Mode is set to API token. Then you should have the options to configure API Token generation, generate new tokens, and revoke existing tokens. Once you have your API token, you may authenticate your API call by adding a `client-id` value containing yourAPI token client ID and a `client-token` value containing your API token client token to your payload. (e.g. `{"client-id": "cccdj-311s", "client-token": "42jkjl-k234jlk1b38123kj3kjl-ffwzzuilaei"}` |
53 | 53 | </details> |
54 | 54 | # Authorization |
|
118 | 118 | ‘Diagnostics > Command Prompt’ and enter the commands there</ul><h1>UI Settings & Documentation</h1><p>After 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.<h3>Notes:</h3><ul><li>Users must hold the <code>page-all</code> or <code>page-system-api</code> privileges to access the API page within the webConfigurator</ul><h1>Authentication</h1><p>By default, pfSense API uses the same credentials as the webConfigurator. This behavior allows you to configure pfSense |
119 | 119 | from the API out of the box, and user passwords may be changed from the API to immediately add additional security if |
120 | 120 | needed. After installation, you can navigate to System > API in the pfSense webConfigurator to configure API |
121 | | -authentication.<p>To authenticate your API call, follow the instructions for your configured authentication mode:<p><details><summary>Local Database (default)</summary |
122 | | - uses the same credentials as the pfsense webconfigurator. to authenticate api calls, simply add a `client-id` value containing your username and a `client-token` value containing your password to your payload. for example `{"client-id": "admin", "client-token": "pfsense"}` |
123 | | -</details><p><details><summary>JWT</summary |
124 | | - requires a bearer token to be included in the `authorization` header of your request. to receive a bearer token, you may make a post request to /api/v1/access_token/ and include a `client-id` value containing your pfsense username and a `client-token` value containing your pfsense password to your payload. for example `{"client-id": "admin", "client-token": "pfsense"}`. once you have your bearer token, you can authenticate your apicall by adding it to the request's authorization header. (e.g. `authorization: bearer xxxxxxxx.xxxxxxxxx.xxxxxxxx`) |
125 | | -</details><p><details><summary>API Token</summary |
126 | | - uses standalone tokens generated via the ui. these are better suited to distribute to systems as they are revocable and will only allow api authentication and not ui or ssh authentication (like the local database credentials). to generate or revoke credentials, navigate to system> API within the UI and ensure the Authentication Mode is set to API token. Then you should have the options to configure API Token generation, generate new tokens, and revoke existing tokens. Once you have your API token, you may authenticate your API call by adding a <code>client-id</code> value containing yourAPI token client ID and a <code>client-token</code> value containing your API token client token to your payload. (e.g. <code>{"client-id": "cccdj-311s", "client-token": "42jkjl-k234jlk1b38123kj3kjl-ffwzzuilaei"}</code></details><h1>Authorization</h1><p>pfSense API uses the same privielges as the pfSense webConfigurator. The required privileges for each endpoint are stated within the API documentation.<h1>Response Codes</h1><p><code>200 (OK)</code> : API call succeeded<br><code>400 (Bad Request)</code> : An error was found within your requested parameters<br><code>401 (Unauthorized)</code> : API client has not completed authentication or authorization successfully<br><code>403 (Forbidden)</code> : The API endpoint has refused your call. Commonly due to your access settings found in <code>System > API</code><br><code>404 (Not found)</code> : Either the API endpoint or requested data was not found<br><code>500 (Server error)</code> : The API endpoint encountered an unexpected error processing your API request<br><h1>Error Codes</h1><p>A full list of error codes can be found by navigating to /api/v1/system/api/errors/ after installation. This will return |
| 121 | +authentication.<p>To authenticate your API call, follow the instructions for your configured authentication mode:<p><details><summary>Local Database (default)</summary> |
| 122 | +Uses the same credentials as the pfSense webConfigurator. To authenticate API calls, simply add a <code>client-id</code> value containing your username and a <code>client-token</code> value containing your password to your payload. For example <code>{"client-id": "admin", "client-token": "pfsense"}</code></details><p><details><summary>JWT</summary> |
| 123 | +Requires a bearer token to be included in the <code>Authorization</code> header of your request. To receive a bearer token, you may make a POST request to /api/v1/access_token/ and include a <code>client-id</code> value containing your pfSense username and a <code>client-token</code> value containing your pfSense password to your payload. For example <code>{"client-id": "admin", "client-token": "pfsense"}</code>. Once you have your bearer token, you can authenticate your APIcall by adding it to the request’s authorization header. (e.g. <code>Authorization: Bearer xxxxxxxx.xxxxxxxxx.xxxxxxxx</code>)</details><p><details><summary>API Token</summary> |
| 124 | +Uses standalone tokens generated via the UI. These are better suited to distribute to systems as they are revocable and will only allow API authentication and not UI or SSH authentication (like the local database credentials). To generate or revoke credentials, navigate to System > API within the UI and ensure the Authentication Mode is set to API token. Then you should have the options to configure API Token generation, generate new tokens, and revoke existing tokens. Once you have your API token, you may authenticate your API call by adding a <code>client-id</code> value containing yourAPI token client ID and a <code>client-token</code> value containing your API token client token to your payload. (e.g. <code>{"client-id": "cccdj-311s", "client-token": "42jkjl-k234jlk1b38123kj3kjl-ffwzzuilaei"}</code></details><h1>Authorization</h1><p>pfSense API uses the same privielges as the pfSense webConfigurator. The required privileges for each endpoint are stated within the API documentation.<h1>Response Codes</h1><p><code>200 (OK)</code> : API call succeeded<br><code>400 (Bad Request)</code> : An error was found within your requested parameters<br><code>401 (Unauthorized)</code> : API client has not completed authentication or authorization successfully<br><code>403 (Forbidden)</code> : The API endpoint has refused your call. Commonly due to your access settings found in <code>System > API</code><br><code>404 (Not found)</code> : Either the API endpoint or requested data was not found<br><code>500 (Server error)</code> : The API endpoint encountered an unexpected error processing your API request<br><h1>Error Codes</h1><p>A full list of error codes can be found by navigating to /api/v1/system/api/errors/ after installation. This will return |
127 | 125 | JSON data containing each error code and their corresponding error message. No authentication is required to view the |
128 | 126 | error code library. This also makes API integration with third-party software easy as the API error codes and messages |
129 | 127 | are always just an HTTP call away!<h1>Queries</h1><p>For endpoints supporting <code>GET</code> 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. |
|
913 | 911 | function IsJsonString(str){try{JSON.parse(str);}catch(e){return false;} |
914 | 912 | return true;} |
915 | 913 | String.prototype.replaceAll=function(replaceThis,withThis){var re=new RegExp(RegExp.quote(replaceThis),"g");return this.replace(re,withThis);};RegExp.quote=function(str){return str.replace(/([.?*+^$[\]\\(){}-])/g,"\\$1");};function syntaxHighlight(json){json=json.replace(/&/g,'&').replace(/</g,'<').replace(/>/g,'>');return json.replace(/("(\\u[a-zA-Z0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\b(true|false|null)\b|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?)/g,function(match){var cls='number';if(/^"/.test(match)){if(/:$/.test(match)){cls='key';}else{cls='string';}}else if(/true|false/.test(match)){cls='boolean';}else if(/null/.test(match)){cls='null';} |
916 | | -return '<span class="'+cls+'">'+match+'</span>';});}</script><br><br><footer class="navbar-default navbar-fixed-bottom"><div class=container-fluid><div class="span12 text-center"><span data-toggle=tooltip title="If the application help you, please feel free to give a star to the project in github. Your star inspire me to work more on open-source projects like this!">Made with <em class=love-color>♥</em> by <a href=https://github.com/thedevsaddam target=_blank class=text-muted>thedevsaddam</a> | Generated at: 2020-09-27 10: 50:11 by <a href=https://github.com/thedevsaddam/docgen target=_blank class=text-muted>docgen</a></span></div></div></footer> |
| 914 | +return '<span class="'+cls+'">'+match+'</span>';});}</script><br><br><footer class="navbar-default navbar-fixed-bottom"><div class=container-fluid><div class="span12 text-center"><span data-toggle=tooltip title="If the application help you, please feel free to give a star to the project in github. Your star inspire me to work more on open-source projects like this!">Made with <em class=love-color>♥</em> by <a href=https://github.com/thedevsaddam target=_blank class=text-muted>thedevsaddam</a> | Generated at: 2020-09-27 10: 51:43 by <a href=https://github.com/thedevsaddam/docgen target=_blank class=text-muted>docgen</a></span></div></div></footer> |
917 | 915 | <style> |
918 | 916 | div.col-md-12.collection-intro, footer{ |
919 | 917 | display:none; |
|
0 commit comments