### API Authentication using Pre-shared Secret Key (curl)

Source: https://api.dnsfilter.com/docs/distributors

Demonstrates how to authenticate API requests using a pre-shared secret key. The 'Authorization' header should be formatted as 'Bearer <distributor_identifier>:<distributor_secret_key>'. This example uses curl to make a GET request to the distributors health endpoint.

```curl
curl --header "Authorization: Bearer qa:5ab321a530095f1210e36add" --request GET "https://api.dnsfilter.com/v1/distributors/health"
```

--------------------------------

### Pagination Example for V1 Endpoints - DNSFilter API

Source: https://api.dnsfilter.com/docs

Demonstrates how to format pagination parameters for V1 endpoints in both JSON and URL query string formats. This is crucial for retrieving data in manageable chunks.

```json
{
  "page[number]": 1,
  "page[size]": 10
}
```

```url
...?page%5Bnumber%5D=1&page%5Bsize%5D=10
```

--------------------------------

### API Pagination Example (URL Parameter)

Source: https://api.dnsfilter.com/docs/distributors

Illustrates how to use URL parameters for API pagination. The 'page[size]' parameter can be appended to endpoint URLs to control the number of items returned per page, with a maximum limit of 1500.

```url
/v1/distributors/msps?page[size]=25
```

--------------------------------

### GET /v1/users/self

Source: https://api.dnsfilter.com/docs

Retrieves information about the currently authenticated user.

```APIDOC
## GET /v1/users/self

### Description
Returns information about the currently authenticated user.

### Method
GET

### Endpoint
`/v1/users/self`

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H 'Authorization: ***' https://api.dnsfilter.com/v1/users/self
```

### Response
#### Success Response (200)
- **data** (object) - Contains the user object.
  - **id** (string) - The user's unique identifier.
  - **type** (string) - The resource type, typically 'users'.
  - **attributes** (object) - Contains user-specific attributes.
    - **name** (string) - The user's name.
    - **email** (string) - The user's email address.

#### Response Example
```json
{
  "data": {
    "id": "12345",
    "type": "users",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "...additional fields..."
    }
  }
}
```
```

--------------------------------

### Fetch Authenticated User Information - cURL Example

Source: https://api.dnsfilter.com/docs

A cURL command to retrieve details of the currently authenticated user via the DNSFilter API's V1 endpoint. Requires an 'Authorization' header with a valid API key.

```bash
% curl -H 'Authorization: ***' https://api.dnsfilter.com/v1/users/self
```

--------------------------------

### Common Error Responses

Source: https://api.dnsfilter.com/docs/distributors

This section details common HTTP status codes and their meanings when interacting with the DNSFilter API, along with example error responses.

```APIDOC
## Common API Error Responses

### Description

ALL API endpoints validate the existence of a valid authorization header. Non-authorized or invalid requests will result in a non-successful HTTP status code. Below are the most common error codes and their meanings.

| HTTP Status | Meaning                                                                   |
|-------------|---------------------------------------------------------------------------|
| 401         | Invalid authentication header                                             |
| 404         | Invalid resource specified or invalid/non-existing endpoint               |
| 422         | Invalid value for an attribute in the payload or value cannot be assigned |
| 500         | Invalid/deleted distributor                                               |

### Error Response Examples

- **401 Unauthorized**: `{"error": "Not Authorized"}`
- **404 Not Found**: `{"error": "invalid MSP"}` or `{"error": "invalid organization"}`
- **422 Unprocessable Entity**: `{"error": "invalid trial_end date 'xxx'"}` or `{"error": "an organization with the specified distributor ID already exists"}`
- **500 Internal Server Error**: `{"error": "service is not configured, please contact support"}`
```

--------------------------------

### User Information Response Structure - DNSFilter API

Source: https://api.dnsfilter.com/docs

Example JSON response structure for fetching user information from the DNSFilter API. It includes user ID, type, and attributes like name and email.

```json
{
  "data": {
    "id": "12345",
    "type": "users",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com",
      "...additional fields..."
    }
  }
}
```

--------------------------------

### API Pagination

Source: https://api.dnsfilter.com/docs/distributors

Some API endpoints support pagination to manage response size. The default number of items returned is 1500, which can be adjusted using the `page[size]` query parameter, with a maximum value of 1500.

```APIDOC
## API Pagination

### Description

To prevent timeouts and manage large response payloads, some API endpoints implement pagination. The default number of items returned per page is 1500.

### Query Parameters

- **page[size]** (integer) - Optional - Specifies the number of items to return per page. The maximum allowed value is 1500.

### Example

`GET /v1/distributors/msps?page[size]=25`

### Response

Pagination information, including the total number of pages, can be found in the `_links` object within the response payload.
```

--------------------------------

### Distributor API Authentication

Source: https://api.dnsfilter.com/docs/distributors

Details on how distributors authenticate with the DNSFilter API using a pre-shared secret key.

```APIDOC
## Distributor API Authentication

### Description
Distributor API endpoints use a pre-shared secret key for authentication. This key is generated when a distributor is created on DNSFilter systems and consists of a distributor identifier and a secret key.

### Authentication Method
Pre-shared Secret Key

### Key Components
1.  **Distributor Identifier**: A friendly name for the distributor using the API.
2.  **Secret Key**: A generated secret key specific to the distributor.

### Read-only Key
Some endpoints, particularly reporting ones, also support a read-only pre-shared secret key. This allows for separate processes that only fetch data.

### API Environments
DNSFilter provides three API environments, each requiring its own set of pre-shared keys:
*   **Production**: `https://api.dnsfilter.com`
*   **Staging**: `https://staging-api-aws.dnsfilter.com`
*   **Development**: `https://api.dev.dnsfilter.sh/`

**Note**: Distributor pre-shared secret keys cannot be recovered once generated. Ensure they are stored securely.
```

--------------------------------

### Pre-shared Secret Key Rotation

Source: https://api.dnsfilter.com/docs/distributors

The process for rotating pre-shared secret keys is manual and requires coordination with DNSFilter support. It involves requesting rotation, DNSFilter generating new keys, the distributor updating their systems, notifying DNSFilter, and finally DNSFilter deactivating the old keys.

```APIDOC
## Pre-shared Secret Key Rotation

### Description

This process allows for the rotation of pre-shared secret keys used for API authentication. It is a manual process that requires coordination with DNSFilter.

### Steps

1.  **Distributor Request**: The distributor requests pre-shared secret keys rotation (both "normal" and read-only) to DNSFilter.
2.  **DNSFilter Key Generation**: DNSFilter generates a new set of secret keys. The distributor identifier remains the same. At this point, both old and new keys are valid.
3.  **Distributor System Update**: The distributor updates its systems with the new pre-shared secret keys.
4.  **Distributor Notification**: The distributor notifies DNSFilter that the secret key values have been updated.
5.  **DNSFilter Old Key Deactivation**: DNSFilter removes the old pre-shared secret keys for the distributor. After this step, the old keys are no longer valid.
```

--------------------------------

### DNSFilter API - Pagination

Source: https://api.dnsfilter.com/docs

Pagination for V1 endpoints uses nested parameters. For query strings, parameters are URL-encoded.

```APIDOC
## Pagination

### Description
For the _V1_ endpoints, the pagination parameters are nested. That is to say, if passed as JSON they look like this: `{"page[number]": 1, "page[size]": 10}`. To pass this information in the URL query string, it would be formatted like this: `...?page%5Bnumber%5D=1&page%5Bsize%5D=10`. In this guide, the UI will indicate that `page` is an `object` and if you want to set values when trying the request, you must enter it as if it was the JSON above.

### Query Parameters
- **page[number]** (integer) - Optional - The page number to retrieve.
- **page[size]** (integer) - Optional - The number of items per page.
```

--------------------------------

### Authentication

Source: https://api.dnsfilter.com/docs/distributors

The DNSFilter API uses a pre-shared secret key for authentication. This key should be included in the 'Authorization' HTTP header, formatted as 'Bearer <distributor_identifier>:<distributor_secret_key>'.

```APIDOC
## Authentication

### Description

The DNSFilter API expects the distributor pre-shared secret key to be contained on the "Authorization" HTTP request header. The value should be composed of the distributor friendly identifier and the distributor secret key, separated by a colon.

### Method

All API requests require authentication.

### Endpoint

All API endpoints.

### Request Example

```bash
curl --header "Authorization: Bearer qa:5ab321a530095f1210e36add" --request GET "https://api.dnsfilter.com/v1/distributors/health"
```

### Response

#### Error Response (401)

- **error** (string) - "Not Authorized"

#### Response Example

```json
{
  "error": "Not Authorized"
}
```
```

--------------------------------

### DNSFilter API - Authentication

Source: https://api.dnsfilter.com/docs

Authentication is required for most endpoints and is handled by setting the 'Authorization' request header with your API key.

```APIDOC
## Authentication

### Description
Authentication is required for most, but not all, endpoints. Authentication is done by setting the `Authorization` request header. The header value is the API key itself. For example: `Authorization: eyJ...`

An API key can be obtained through the DNSFilter dashboard under Account Settings. For additional information see this KB article.

### Method
All requests requiring authentication must include the `Authorization` header.

### Headers
- **Authorization** (string) - Required - Your API key.
```

--------------------------------

### DNSFilter API - Error Handling

Source: https://api.dnsfilter.com/docs

The API uses standard HTTP status codes for success and failure. Error response formats differ between V1 and V2 endpoints.

```APIDOC
## Error Handling

### Description
The API uses standard HTTP status codes to indicate success or failure. For _V1_ endpoints the response format is: `{ "error": "string", "type": "string(optional)" }`. For _V2_ endpoints the response format is: `{ "error": { "message": "string", "type": "string(optional)" } }`.

### Response Codes
- **4xx** - Client errors
- **5xx** - Server errors
```

--------------------------------

### DNSFilter API - Rate Limiting

Source: https://api.dnsfilter.com/docs

All endpoints are subject to rate limiting. Exceeding the limit will result in a 429 HTTP status code.

```APIDOC
## Rate Limiting

### Description
All endpoints are rate limited. The limits may vary by endpoint, but are generally consistent. When the rate limit is exceeded the API will return the standard `429` HTTP status. The following headers will also be provided in the response: `Retry-After`, `RateLimit-Policy`, `RateLimit`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### Headers
- **Retry-After** (integer) - The number of seconds to wait before retrying.
- **RateLimit-Policy** (string) - Describes the rate limit policy.
- **RateLimit** (string) - The total number of requests allowed in the current window.
- **RateLimit-Limit** (integer) - The maximum number of requests allowed.
- **RateLimit-Remaining** (integer) - The number of requests remaining in the current window.
- **RateLimit-Reset** (integer) - The time in seconds until the rate limit resets.
```

--------------------------------

### V1 Error Response Format - DNSFilter API

Source: https://api.dnsfilter.com/docs

Illustrates the JSON structure for error responses from V1 endpoints of the DNSFilter API. It includes a mandatory 'error' field and an optional 'type' field.

```json
{
  "error": "string",
  "type": "string(optional)"
}
```

--------------------------------

### V2 Error Response Format - DNSFilter API

Source: https://api.dnsfilter.com/docs

Shows the JSON format for error responses from V2 endpoints of the DNSFilter API. Errors are nested within an 'error' object containing 'message' and an optional 'type'.

```json
{
  "error": {
    "message": "string",
    "type": "string(optional)"
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.