The Proxy Layer

The proxy layer is the core of Skillett’s architecture. Every request to an external service flows through it, ensuring credentials are never exposed to agents.

How it works

When a skill is executed (POST /v1/:integration/:endpoint), the proxy layer:

1. Validates the API key — Checks the Bearer token against the hashed keys in the database
2. Checks plan limits — Verifies the user hasn’t exceeded their daily API call limit
3. Loads credentials — Retrieves the encrypted OAuth tokens for the user’s connection
4. Maps parameters — Transforms CLI parameters to the external API’s expected format (e.g., repo: "acme/app" → URL path segments owner and repo)
5. Injects authentication — Adds the OAuth token to the request headers
6. Forwards the request — Sends the request to the external service
7. Returns the response — Wraps the upstream response in a standard JSON envelope

Token refresh

When the upstream API returns a 401 Unauthorized, the proxy automatically:

1. Attempts to refresh the OAuth token using the stored refresh token
2. If refresh succeeds, retries the original request with the new token
3. If refresh fails, returns a token_expired error with an action_url to reconnect

This is a reactive approach — tokens are refreshed only when they fail, not proactively on a clock. This is simpler and handles edge cases better (like provider-side revocation).

Credential security

• OAuth tokens are encrypted at rest in the database
• Tokens are decrypted only in memory during request processing
• API keys are hashed — the plaintext key is never stored
• The proxy layer runs server-side — agents never see OAuth tokens
• Rate limiting is applied per API key and per connection

Parameter mapping

Each endpoint’s frontmatter defines how CLI parameters map to upstream API parameters:

param_mapping:
  repo: owner/repo → {owner}, {repo}

This tells the proxy that when the user passes --repo acme/webapp, it should:

• Split on / to extract owner=acme and repo=webapp
• Insert them into the URL path: /repos/acme/webapp/issues

Common mapping patterns:

• Path segments — Parameters inserted into the URL
• Query parameters — Appended as ?key=value
• Body fields — Included in the JSON request body
• Headers — Set as request headers

Error handling

The proxy translates upstream errors into Skillett’s standard error format:

Upstream	Skillett error	Meaning
401	token_expired	OAuth token expired (after refresh attempt)
403	Forwarded as-is	Insufficient permissions on the external service
404	Forwarded as-is	Resource not found on the external service
429	Forwarded as-is	Rate limited by the external service
5xx	Forwarded as-is	External service error

Skillett-level errors (bad API key, plan limits, not connected) are caught before the request reaches the proxy.