API Reference

As an AI company you can use paywalls.net API services to programmatically request access tokens and refresh access tokens when they expire. This section provides the API reference for these endpoints.

API Guide

The payalls.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 (other than OAuth token refresh 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

Client Registration

This endpoint allows you to register a new client application programmatically. It follows the OAuth 2.0 Dynamic Client Registration specification. See RFC 7591

Endpoint

POST /api/agents/register

Headers

Request Body

Example Request

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

{
  "client_name": "Example Client",
  "client_uri": "https://example.com",
  "contacts": ["[email protected]"],
  "software_id": "example-software-id",
  "software_version": "1.0.0"
}

Example Response

{
  "client_id": "CLIENT_ID_VALUE",
  "client_id_issued_at": 1618886400,
  "client_name": "Example Client",
  "client_uri": "https://example.com",
  "contacts": ["[email protected]"],
  "software_id": "example-software-id",
  "software_version": "1.0.0",
  "grant_types": ["refresh_token"],
  "token_endpoint_auth_method": "none",
  "response_types": ["token"],
  "scope": "publisher-resources"
}

Notes

• Ensure the Authorization header contains a valid API key.
• The client_id is a unique identifier for the registered client application.

Authorization

This endpoint grants the client access to publisher resources and provides both a refresh token and an access token for the agent. The refresh token serves as a 'user identity' token and does not expire. The access token is valid for 15 minutes.

Note A refresh token 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.

Endpoint

POST /api/agents/access

Headers

Request Body

Example Request

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

{
  "scope": "publisher-resources",
  "client_id": "<agent-client-id>"
}

Example Response

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN_VALUE",
  "refresh_token": "REFRESH_TOKEN_VALUE",
  "expires_in": 900
}

Notes

• Ensure the Authorization header contains a valid API key.
• The access_token is valid for 15 minutes and must be refreshed using the refresh_token when expired.

Access Token Refresh

This endpoint provides a new access token to replace an expired access token using a valid refresh token. The new access token will be valid for 15 minutes.

Endpoint

POST /api/oauth/refresh

Description

Headers

Request Body

Example Request

POST /api/oauth/refresh HTTP/1.1
Host: cloud-api.paywalls.net
Content-Type: application/json

{
  "client_id": "<agent-client-id>",
  "grant_type": "refresh_token",
  "refresh_token": "<refresh-token>"
}

Example Response

{
  "token_type": "Bearer",
  "access_token": "NEW_ACCESS_TOKEN_VALUE",
  "expires_in": 900
}

Notes

• No API Key is required for this endpoint and should not be sent.
• Ensure the refresh_token is valid and has not expired.
• The access_token is valid for 15 minutes and must be refreshed again when expired.

Agent Status

This endpoint validates the agent operator, agent, and token, and returns the status based on publisher policy.

Endpoint

POST /api/filter/agents/auth

Headers

Request Body

Response Body