Generic HTTP

The http-token provider type connects agents to any REST API that authenticates with a static token — injected either as an HTTP header or a URL query parameter. No code changes needed; configure everything in the Provider YAML.

This covers services like Serper, SerpApi, Stripe, Twilio, SendGrid, Notion, Linear, and any other API with a simple token-based auth scheme.

Get credentials

Get the API token from your upstream service — the process varies (account settings, developer console, support ticket). Whatever the service gives you goes into a Pai secret.

Setup

Store the token, then create a Provider. There are two auth shapes:

Header injection (default)

Most APIs accept a token in the Authorization: Bearer <token> header:

pai add secret my-api-key --from-literal token=YOUR_TOKEN

apiVersion: pai.io/v1
kind: Provider
metadata:
  name: my-api
spec:
  type: http-token
  host: api.example.com
  auth:
    type: api-key
    secretRef: my-api-key
    # header defaults to "Authorization", prefix defaults to "Bearer "
  policy:
    allow: ["*"]

For custom header names or no prefix:

auth:
  type: api-key
  secretRef: serper-key
  header: X-API-KEY       # custom header name
  prefix: ""              # no "Bearer " prefix

Query parameter injection

Some APIs (SerpApi, etc.) expect the key as a URL query parameter:

auth:
  type: api-key
  secretRef: serpapi-key
  param: api_key          # injected as ?api_key=<token>

Config fields

Field	Description
host	Hostname of the upstream API (e.g. api.stripe.com)
auth.type	api-key
auth.secretRef	Pai secret name containing the token
auth.secretKey	Key within the secret (default token)
auth.header	Header name for token injection (default Authorization)
auth.prefix	Prefix for the header value (default Bearer )
auth.param	Query-parameter name; set this instead of header for query-string auth

Examples

Serper (Google Search API):

apiVersion: pai.io/v1
kind: Provider
metadata:
  name: serper-search
spec:
  type: http-token
  host: google.serper.dev
  auth:
    type: api-key
    secretRef: serper-key
    header: X-API-KEY
    prefix: ""
  policy:
    allow: ["*"]

Stripe — read-only:

apiVersion: pai.io/v1
kind: Provider
metadata:
  name: stripe-readonly
spec:
  type: http-token
  host: api.stripe.com
  auth:
    type: api-key
    secretRef: stripe-key
  policy:
    httpRules:
      - methods: [GET]
        paths: ["*"]
        effect: allow
      - methods: [POST, PUT, PATCH, DELETE]
        paths: ["*"]
        effect: deny

Notion:

apiVersion: pai.io/v1
kind: Provider
metadata:
  name: notion
spec:
  type: http-token
  host: api.notion.com
  auth:
    type: api-key
    secretRef: notion-key
  policy:
    allow: ["*"]

Attach to an agent

spec:
  providers:
    - serper-search
    - stripe-readonly
    - notion

Access control

http-token providers don't have a built-in action catalogue, so HTTP-level rules (policy.httpRules) are the main tool for narrowing. Combine method + path globs to limit what the agent can do. See the Policy reference for the full field list and examples.