Skip to main content

Generic HTTP Provider

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.

Header injection (default)​

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

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>

Examples​

Serper (Google Search API)​

pai add secret serper-key --from-literal token=YOUR_SERPER_KEY
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​

pai add secret stripe-key --from-literal token=sk_live_...
apiVersion: pai.io/v1
kind: Provider
metadata:
  name: stripe
spec:
  type: http-token
  host: api.stripe.com
  auth:
    type: api-key
    secretRef: stripe-key
  policy:
    allow: ["*"]
    httpRules:
      - methods: [GET]
        paths: ["*"]
        effect: allow
      - methods: [DELETE]
        paths: ["*"]
        effect: deny

Notion​

pai add secret notion-key --from-literal token=secret_...
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