Documentation
¶
Overview ¶
Package apikeys manages API keys and MCP agents (A5 §3.9, §5.13). Keys never exceed their creator's permissions and are shown exactly once. Expired keys stay listed for 90 days with the calls that still try to use them.
Index ¶
- Constants
- func ClientLabel(ua string) string
- func PickedFirst(picked []string, set authz.Set) []string
- func RecordRejection(ctx context.Context, q *store.Queries, keyID uuid.UUID, ip *netip.Addr, ...)
- func Register(h huma.API, s *Service)
- func StoredOrder(keys []string) []string
- type APIKeyAllowedIPsInput
- type APIKeyCategoryRef
- type APIKeyCreateInput
- type APIKeyCreated
- type APIKeyCreator
- type APIKeyList
- type APIKeyLockedPermission
- type APIKeyRejections
- type APIKeyTransactional
- type APIKeyTransactionalInput
- type APIKeyView
- type KeyPathInput
- type MCPAgentAction
- type MCPAgentActionList
- type Service
- func (s *Service) AgentActions(ctx context.Context, ws *store.Workspace, limit int) (MCPAgentActionList, error)
- func (s *Service) Create(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, ...) (APIKeyCreated, error)
- func (s *Service) Delete(ctx context.Context, ws *store.Workspace, kind string, id uuid.UUID) error
- func (s *Service) Get(ctx context.Context, ws *store.Workspace, kind string, id uuid.UUID) (APIKeyView, error)
- func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string) (APIKeyList, error)
- func (s *Service) Revoke(ctx context.Context, ws *store.Workspace, kind string, id uuid.UUID) error
- func (s *Service) Rotate(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, ...) (APIKeyCreated, error)
- func (s *Service) SetAllowedIPs(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, ...) (APIKeyView, error)
Constants ¶
const ( KindAPIKey = "api_key" KindAgent = "mcp_agent" )
Kinds of keys.
const ( PresetSendOnly = "send_only" PresetSMTP = "smtp" )
Send-only key presets.
Variables ¶
This section is empty.
Functions ¶
func ClientLabel ¶
ClientLabel turns a User-Agent into a short label for the keys list: "GitHub Actions runner", "Claude Desktop", "curl", "python-requests".
func PickedFirst ¶
PickedFirst stores the picked keys in their order, then the implied ones.
func RecordRejection ¶
func RecordRejection(ctx context.Context, q *store.Queries, keyID uuid.UUID, ip *netip.Addr, userAgent, reason string)
RecordRejection counts a call refused because a key expired, was revoked or came from an address its allowed IPs don't include, so the keys screen can show what still uses it. The REST middleware and the MCP endpoint call it. A refused address is kept as its /64 for IPv6 (one host holds many), and a key keeps at most 1,000 addresses a day (KeysRecordRejection).
func StoredOrder ¶
StoredOrder returns the keys the creator picked, in the order picked, without the view permissions that were added automatically.
Types ¶
type APIKeyAllowedIPsInput ¶
type APIKeyAllowedIPsInput struct {
AllowedIPs []string `` /* 145-byte string literal not displayed */
}
APIKeyAllowedIPsInput replaces the addresses and networks a key may be called from.
type APIKeyCategoryRef ¶
APIKeyCategoryRef names a transactional category.
type APIKeyCreateInput ¶
type APIKeyCreateInput struct {
Name string `json:"name" minLength:"1" maxLength:"80"`
Description string `json:"description,omitempty" maxLength:"120" doc:"Client label, e.g. Claude Desktop"`
Permissions []string `json:"permissions" minItems:"1" maxItems:"60"`
// Lists restricts the key to these lists (empty = all lists).
Lists []string `json:"lists,omitempty" maxItems:"100"`
ExpiresAt *time.Time `json:"expiresAt,omitempty"`
// Transactional makes a send-only, test-mode or SMTP key; its only
// permission is then transactional:send.
Transactional *APIKeyTransactionalInput `json:"transactional,omitempty"`
// AllowedIPs limits the key to calls from these addresses and networks
// (empty = any address).
AllowedIPs []string `` /* 155-byte string literal not displayed */
}
APIKeyCreateInput creates a key or agent.
type APIKeyCreated ¶
type APIKeyCreated struct {
Key APIKeyView `json:"key"`
Secret string `json:"secret" doc:"The full key. Shown only in this response."`
// Usage is "Authorization: Bearer rc_live_… against https://…/api/v1".
Endpoint string `json:"endpoint"`
}
APIKeyCreated is shown exactly once.
type APIKeyCreator ¶
type APIKeyCreator struct {
ID string `json:"id,omitempty"`
Name string `json:"name"`
AvatarColor string `json:"avatarColor"`
}
APIKeyCreator is who created a key.
type APIKeyList ¶
type APIKeyList struct {
Items []APIKeyView `json:"items"`
// Permissions, Held, Locked and Lists feed the create dialog.
Permissions []access.PermissionInfo `json:"permissions"`
Groups []string `json:"groups"`
Held []string `json:"held"`
Locked []APIKeyLockedPermission `json:"locked"`
Lists []access.ScopedList `json:"lists"`
// Endpoint is the API base URL (or the MCP endpoint for agents).
Endpoint string `json:"endpoint"`
// YourIP and ProxyWarning feed the allowed IPs field: the caller's
// address as ReputeCast sees it, and whether that may be a proxy's.
YourIP string `json:"yourIp" doc:"The address of this request as ReputeCast resolved it; empty when unknown"`
ProxyWarning bool `` /* 152-byte string literal not displayed */
}
APIKeyList is the API keys or MCP agents card.
type APIKeyLockedPermission ¶
APIKeyLockedPermission is a permission the caller can't put on a key.
type APIKeyRejections ¶
type APIKeyRejections struct {
Calls int64 `json:"calls" doc:"In the last 7 days"`
Since *time.Time `json:"since,omitempty" doc:"First rejected call"`
IP string `json:"ip,omitempty" doc:"Busiest client address"`
Client string `json:"client,omitempty" doc:"Client label of that address"`
}
APIKeyRejections counts calls refused because the key expired or was revoked, or came from an address its allowed IPs don't include.
type APIKeyTransactional ¶
type APIKeyTransactional struct {
Preset string `json:"preset" enum:"send_only,smtp"`
Mode string `json:"mode" enum:"live,test"`
Templates []string `json:"templates" doc:"Template IDs it may send; empty for all, including ones published later"`
Categories []APIKeyCategoryRef `json:"categories" doc:"Categories it may send (SMTP credentials); empty for all"`
TestAddresses []string `json:"testAddresses" doc:"Allowed test addresses besides the members (qa+*@acme.io)"`
RatePerSecond int `json:"ratePerSecond"`
// Username is an SMTP credential's user name: the key's ID.
Username string `json:"username,omitempty"`
}
APIKeyTransactional describes a send-only key: its preset (send_only, or smtp for an SMTP relay credential), its mode (test keys deliver only to the workspace's members and the allowed test addresses), the templates or categories it is limited to, and its send rate.
type APIKeyTransactionalInput ¶
type APIKeyTransactionalInput struct {
Preset string `json:"preset" enum:"send_only,smtp"`
Mode string `json:"mode,omitempty" enum:"live,test" default:"live"`
// Templates limits the key to these template IDs (empty: all, including
// ones published later).
Templates []string `json:"templates,omitempty" maxItems:"200"`
// Categories limits the key to these categories (SMTP credentials).
Categories []string `json:"categories,omitempty" maxItems:"50"`
// TestAddresses are allowed besides the workspace's members (test mode):
// addresses or patterns such as qa+*@acme.io.
TestAddresses []string `json:"testAddresses,omitempty" maxItems:"50"`
RatePerSecond int `json:"ratePerSecond,omitempty" minimum:"1" maximum:"10000" doc:"Messages per second (50 by default)"`
}
APIKeyTransactionalInput is the "Send-only key" preset of the create dialog, and an SMTP credential.
type APIKeyView ¶
type APIKeyView struct {
ID string `json:"id"`
Kind string `json:"kind" enum:"api_key,mcp_agent"`
Name string `json:"name"`
Description string `json:"description" doc:"Client label for agents (Claude Desktop)"`
Masked string `json:"masked" example:"rc_live_8f2c…a91d"`
Permissions []string `json:"permissions"`
Sensitive []string `json:"sensitive" doc:"The ⚑ permissions among them"`
Scope access.ScopeSummary `json:"scope"`
CreatedBy APIKeyCreator `json:"createdBy"`
CreatedAt time.Time `json:"createdAt"`
ExpiresAt *time.Time `json:"expiresAt,omitempty"`
LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
LastUsedIP string `json:"lastUsedIp,omitempty"`
// LastUsedClient labels the caller ("nightly job", "GitHub Actions runner").
LastUsedClient string `json:"lastUsedClient,omitempty"`
// LastCall is the MCP tool of an agent's last call.
LastCall string `json:"lastCall,omitempty"`
Status string `json:"status" enum:"active,expired"`
Rejections *APIKeyRejections `json:"rejections,omitempty"`
// Transactional is set for send-only, test-mode and SMTP keys.
Transactional *APIKeyTransactional `json:"transactional,omitempty"`
// AllowedIPs are the addresses and networks the key may be called from;
// empty: any address.
AllowedIPs []string `` /* 126-byte string literal not displayed */
}
APIKeyView is an API key or MCP agent as listed. The secret is never returned.
type KeyPathInput ¶
type KeyPathInput struct {
api.WorkspaceInput
KeyID string `path:"keyId" format:"uuid"`
}
KeyPathInput is a path or query input shared by several operations.
type MCPAgentAction ¶
type MCPAgentAction struct {
ID string `json:"id"`
OccurredAt time.Time `json:"occurredAt"`
AgentID string `json:"agentId,omitempty"`
Agent string `json:"agent"`
Tool string `json:"tool"`
Target string `json:"target"`
Result string `json:"result" enum:"allowed,denied,error"`
// Note is "campaigns:pause" for an allowed call or "needs campaigns:send ·
// proposal recorded for Linh Nguyen" for a denied one.
Note string `json:"note,omitempty"`
// Proposal tells that a denied call was proposed to a member to review.
Proposal bool `json:"proposal"`
// Summary is what the tool returned or did ("Paused October Product Update · Outlook route").
Summary string `json:"summary,omitempty"`
}
MCPAgentAction is one recent MCP tool call.
type MCPAgentActionList ¶
type MCPAgentActionList struct {
Items []MCPAgentAction `json:"items"`
}
MCPAgentActionList is the recent agent actions card.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
PublicURL func(context.Context) string
Now func() time.Time
// ProxyWarning reports that requests reach ReputeCast through a proxy it
// doesn't trust, so the addresses it sees may be the proxy's
// (internal/proxycheck). Nil: no warning.
ProxyWarning func(context.Context) bool
}
func (*Service) AgentActions ¶
func (s *Service) AgentActions(ctx context.Context, ws *store.Workspace, limit int) (MCPAgentActionList, error)
AgentActions lists the latest MCP calls from the audit log, their details, notes and outcomes in the reader's language when the agent's call kept them (internal/mcpserver).
func (*Service) Create ¶
func (s *Service) Create(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, in APIKeyCreateInput) (APIKeyCreated, error)
Create makes a key or agent with permissions the caller holds.
func (*Service) Get ¶
func (s *Service) Get(ctx context.Context, ws *store.Workspace, kind string, id uuid.UUID) (APIKeyView, error)
Get returns one key with its rejected calls.
func (*Service) List ¶
func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string) (APIKeyList, error)
List returns the keys (or agents) of the workspace.
func (*Service) Rotate ¶
func (s *Service) Rotate(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, id uuid.UUID) (APIKeyCreated, error)
Rotate replaces a key (active or expired) with a new secret that has the same name, permissions, scope and allowed IPs. The old one stops working at once.
func (*Service) SetAllowedIPs ¶
func (s *Service) SetAllowedIPs(ctx context.Context, ws *store.Workspace, p *authz.Principal, kind string, id uuid.UUID, in APIKeyAllowedIPsInput) (APIKeyView, error)
SetAllowedIPs replaces a key's allowed IPs. Narrowing them needs only the manage permission; letting the key be called from more addresses (an empty list, or a network the old list doesn't cover) needs what rotating it needs: its permissions and its lists within the caller's own. Integrations' keys are called from their platforms' servers and never get a list; revoked keys keep theirs.