Documentation
¶
Overview ¶
Package auth decides how a request identifies itself to the API.
There are two families, and the second is why this package exists. STATIC is what every tool does: a bearer, an API key, a basic — a fixed value, from a flag, applied to every call. DYNAMIC is what many production APIs require: trading key+secret for a short-lived JWT, typically valid for an hour or two. With static auth, an MCP server for those APIs works until the token expires and then returns 401 until somebody restarts it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Basic ¶
type Basic struct{ User, Password string }
Basic sets `Authorization: Basic <base64(user:password)>`.
type Chain ¶ added in v1.10.0
type Chain []Applier
Chain applies several appliers in order, stopping at the first failure.
type Flow ¶
type Flow struct {
// URL of the endpoint that issues the token.
URL string
// Fields sent as form-urlencoded, which is what authentication endpoints usually accept.
Fields map[string]string
// TokenPath says where the token sits in the JSON response, as nested keys.
// E.g. {"data":{"token":"x"}} → []string{"data","token"}.
TokenPath []string
// TTL is how long the token is valid. The renewal margin is derived from it.
TTL time.Duration
// Client is injectable for tests.
Client *http.Client
// contains filtered or unexported fields
}
Flow is dynamic auth: it trades credentials for a short-lived token and renews it on its own.
The token is kept in memory and renewed BEFORE it expires, with a margin. Renewing on a 401 would also work, but it burns one call every couple of hours and turns a predictable event into a visible failure for whoever is on the other side.
func (*Flow) Invalidate ¶
func (f *Flow) Invalidate()
Invalidate throws away the stored token — for when the API answered 401 despite the validity it announced itself. The next call authenticates again.
type RequestID ¶ added in v1.10.0
type RequestID struct{}
RequestID fills `{uuid}` in the fixed headers with a fresh v4, one per request.
A whole family of APIs demands a unique id on every call — eToro requires `x-request-id` on all of its operations — and `--header 'x-request-id=...'` with a fixed value would send the SAME id forever, which is exactly what such a header exists to prevent.
Unlike `{timestamp}`, this placeholder stands on its own: no signature covers it, so it is expanded here instead of in Signature.Apply, and it works for APIs that sign nothing at all. It is chained ahead of whatever authentication was configured, so both can hold placeholders without either one seeing the other's.
type Signature ¶ added in v1.3.0
type Signature struct {
// Algo is `sha256` (plain hash of the payload) or `hmac-sha256` (keyed by Secret).
Algo string
// Payload is the template of the string to sign.
Payload string
// Into says where the signature goes: `header:Name=template` or `query:name=template`.
Into string
// Encoding is how the signature bytes become text: `hex` (default) or `base64`. Both are
// common; picking the wrong one fails every call with an authentication error that never
// mentions encoding.
Encoding string
// Query are fixed query parameters added to every call, expanded like the payload and set
// BEFORE the signature is computed — so a scheme that signs the query signs them too.
Query map[string]string
// TimestampFormat is what {timestamp} expands to: `unix` (default, seconds since the epoch),
// `unix-ms` (milliseconds) or `iso8601-ms` (2020-12-08T09:08:57.715Z). APIs that reject a request whose timestamp
// drifts by more than a few seconds usually want the second one.
TimestampFormat string
AppID string
Secret string
}
Signature is per-request authentication: instead of carrying a fixed token, each call is signed over its own content. Shopee's affiliate API and TikTok Shop's both work this way, and no amount of bearer/apikey configuration reaches them — the credential is not a value, it is a computation.
The shapes differ (Shopee hashes appId+timestamp+body+secret into an Authorization header; TikTok HMACs path+query+body into a `sign` query parameter), so what is configurable here is the RECIPE: which algorithm, which string gets signed, and where the result goes.
Placeholders, usable in both Payload and Into:
{app_id} {secret} the credentials
{timestamp} computed per request; format set by TimestampFormat
{method} the HTTP verb, uppercase (GET, POST…)
{body} {path} {query} the request itself ({query} sorted, `k=v` joined, no separator)
{signature} the result (Into only)
The same {timestamp} value is used in the payload and in Into, so a scheme that signs the timestamp AND sends it in a header stays consistent — sign one instant and send another and every call fails with a signature error that says nothing about clocks.