API Reference

As a publisher, you can use paywalls.net API services to check the validity of an access token and to log access requests (for reporting and billing). This section provides the API reference for these endpoints.

Note paywalls.net provides clients for several popular CDNs that can be used to filter bot requests. The following API reference can be used if you want to build your own client or if you are using a language that does not have a client available. The API reference is also useful for understanding the underlying API calls that are made by the clients.

API Guide

The paywalls.net API services are hosted at https://cloud-api.paywalls.net. All API requests should be made to this base URL. The API is a RESTful service that uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources.

All API requests must provide an API Key in the request header. The API Key is used to authenticate your requests and ensure that only authorized clients can access the API.

The API Key should be included in the Authorization header of your requests, formatted as follows:

Authorization: Bearer YOUR_API_KEY

Note An API Key is extremely sensitive and should be treated like a password. Do not share it with anyone or store it in your code. Use environment variables or secure vaults to store it securely.

Requests with a body should send the content as application/json and include the Content-Type header:

Content-Type: application/json

API Endpoints

Agent Status

The Agent Status endpoint is used to validate the user agent based on the operator, agent, and optional OAuth access token, and return the status based on publisher policy.

Endpoint

POST /api/filter/agents/auth

Headers

Request Body

Example Request

POST /api/filter/agents/auth HTTP/1.1
Host: api.paywalls.net
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "account_id": "<account-id>",
  "operator": "<operator-name>",
  "agent": "<agent-name>",
  "token": "<access-token>"
}

Example Response

{
  "accountId": "<account-id>",
  "agentId": "<agent-id>",
  "token": "<access-token>",
  "access": "allow | deny",
  "reason": "unknown_error | usage_allowed | usage_not_allowed | user_agent_unrecognized | token_not_found | token_disabled | token_expired | token_active"
}

Valid Values for reason

• token_not_provided: The token was not provided in the request.
• token_not_found: The token could not be found.
• token_disabled: The token has been disabled.
• token_expired: The token has expired.
• token_active: The token is active and valid.
• usage_allowed : The content usage by this agent is allowed.
• usage_not_allowed: The content usage by this agent is not allowed.

Notes

• Ensure the Authorization header contains a valid API key.
• The reason field provides detailed information about the access decision.

Log Access Requests

The Log Access Requests endpoint is used to log access requests for reporting and billing purposes.

Endpoint

POST /api/filter/access/logs

Headers

Request Body

status Object

Example Request

POST /api/filter/access/logs HTTP/1.1
Host: api.paywalls.net
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "account_id": "<account-id>",
  "status": {
    "token": "<access-token>",
    "access": "allow",
    "reason": "usage_allowed",
    "time_remaining": 900
  }
}

Example Response

{ "message": "Accepted" }

Notes

• Ensure the Authorization header contains a valid API key.
• The response status will be 202 Accepted if the request was successful.