Skip to content

Commit

Permalink
docs: link to swagger in mkdocs site
Browse files Browse the repository at this point in the history
  • Loading branch information
jaredhendrickson13 committed May 19, 2024
1 parent 7b4f544 commit 206b437
Show file tree
Hide file tree
Showing 3 changed files with 15 additions and 10 deletions.
19 changes: 11 additions & 8 deletions docs/AUTHENTICATION_AND_AUTHORIZATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

There are three authentication methods available for the pfSense REST API out of the box. The allowed authentication methods
can be configured in the pfSense webConfigurator under `System` -> `REST API` -> `Settings` -> `Authentication Methods`
or via a `PATCH` request to the `/api/v2/system/restapi/settings` endpoint's `auth_methods` field. In addition to these
methods, custom authentication methods can be added by extending the `Auth` class and implementing your own authentication
logic.
or via a `PATCH` request to the [/api/v2/system/restapi/settings](https://pfrest.org/api-docs/#/SYSTEM/RESTAPI%5CEndpoints%5CSystemRESTAPISettingsEndpoint-patch)
endpoint's `auth_methods` field. In addition to these methods, custom authentication methods can be added by extending
the `Auth` class and implementing your own authentication logic.

!!! Note
Multiple authentication methods can be enabled at the same time. If multiple methods are
Expand Down Expand Up @@ -41,8 +41,8 @@ curl -u admin:pfsense https://pfsense.example.com/api/v2/firewall/rules
API key authentication is a more secure form of authentication that requires the client to send an `X-API-Key` header
containing a valid API key. These keys are better suited to distribute to systems as they cannot allow webConfigurator
or SSH authentication (like local database credentials can). API keys can be generated in the pfSense webConfigurator
under `System` -> `REST API` -> `Keys` or by `POST` request to /api/v2/auth/key. Below is an example of API Key
authentication using `curl`:
under `System` -> `REST API` -> `Keys` or by `POST` request to [/api/v2/auth/key](https://pfrest.org/api-docs/#/AUTH/RESTAPI%5CEndpoints%5CAuthKeyEndpoint-post).
Below is an example of API Key authentication using `curl`:

```bash
curl -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxx" https://pfsense.example.com/api/v2/firewall/rules
Expand All @@ -52,13 +52,15 @@ curl -H "X-API-Key: xxxxxxxxxxxxxxxxxxxxxxx" https://pfsense.example.com/api/v2/
API keys utilize the privileges assigned to the user that generated the key.
!!! Warning
API keys are sensitive information and should be treated as such. Do not share your API key with anyone you do not
trust. If you believe your API key has been compromised, you can revoke it in the pfSense webConfigurator.
trust. If you believe your API key has been compromised, you can revoke it in the pfSense webConfigurator or by
making a DELETE request to the [/api/v2/auth/key](https://pfrest.org/api-docs/#/AUTH/RESTAPI%5CEndpoints%5CAuthKeyEndpoint-delete) endpoint.

### JSON Web Token (JWT) Authentication

JSON Web Token (JWT) authentication is a stateless, secure authentication method that uses a signed token to authenticate
users. This method requires the client to send a `Bearer` token in the `Authorization` header. The token is signed with
a secret key that only the REST API and the client know. JWT tokens can be generated using the `/api/v2/auth/jwt` endpoint
a secret key that only the REST API and the client know. JWT tokens can be generated using the
[/api/v2/auth/jwt](https://pfrest.org/api-docs/#/AUTH/RESTAPI%5CEndpoints%5CAuthJWTEndpoint-post) endpoint
and require the client to authenticate as a local database user. Below is an example of receiving a JWT token using
`curl`:

Expand All @@ -76,7 +78,8 @@ curl -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx" https://pfsense.example.
!!! Important
JWTs are only valid for a limited time (default 1 hour) and must be regenerated after they expire. The expiration
interval can be configured in the REST API settings within the pfSense webConfigurator or via a `PATCH` request to
the `/api/v2/system/restapi/settings` endpoint's `jwt_exp` field.
the [/api/v2/system/restapi/settings](https://pfrest.org/api-docs/#/SYSTEM/RESTAPI%5CEndpoints%5CSystemRESTAPISettingsEndpoint-patch)
endpoint's `jwt_exp` field.

### Custom Authentication

Expand Down
3 changes: 2 additions & 1 deletion docs/INSTALL_AND_CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/re

The REST API is designed to be used out of the box. However, there are a number of configuration options available to
you to customize the API to your needs. The REST API settings can be configured in pfSense webConfigurator under
`System` -> `REST API` or via `PATCH` request to the /api/v2/system/restapi/settings endpoint.
`System` -> `REST API` or via `PATCH` request to the [/api/v2/system/restapi/settings](https://pfrest.org/api-docs/#/SYSTEM/RESTAPI%5CEndpoints%5CSystemRESTAPISettingsEndpoint-patch)
endpoint.

## Deleting the package

Expand Down
3 changes: 2 additions & 1 deletion docs/WORKING_WITH_HATEOAS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ easily navigate the API and discover available actions and resources related to
with some [custom link types](#link-types).
- HATEOAS is an optional feature and is disabled by default. HATEOAS can be enabled in the
pfSense webConfigurator under `System` -> `REST API` -> `Settings` by checking the `Enable HATEOAS` checkbox or
via a `PATCH` request to the `/api/v2/system/restapi/settings` endpoint's `hateoas` field.
via a `PATCH` request to the [/api/v2/system/restapi/settings](https://pfrest.org/api-docs/#/SYSTEM/RESTAPI%5CEndpoints%5CSystemRESTAPISettingsEndpoint-patch)
endpoint's `hateoas` field.
!!! Important
Enabling HATEOAS can greatly increase the size of API responses as additional links are included in the response data;
which may also impact performance on large datasets.
Expand Down

0 comments on commit 206b437

Please sign in to comment.