minter

Documentation

Overview

Package minter mints embed tokens used by the Everscribe embeddable component to display audit events from a customer's frontend without exposing the project API key.

An embed token is a short-lived, signed JWT minted by the customer's backend (using the project API key) and forwarded to the frontend. The frontend passes it to the React component, which authenticates read-only requests to /v1/embed/events.

See the sdk-go README "Embedded views" section for the full flow.

Index

• Constants
• type Client
  • func New(projectID, apiKey string, opts ...Option) *Client
  • func (c *Client) MintToken(ctx context.Context, opts TokenOptions) (string, error)
• type Error
  • func (e *Error) Error() string
• type Option
  • func WithBaseURL(url string) Option
  • func WithHTTPClient(c *http.Client) Option
• type TokenOptions

Constants

const (
	MinExpiresIn = 60 * time.Second
	MaxExpiresIn = 24 * time.Hour
)

Lifetime bounds enforced by the server. ExpiresIn outside this range is rejected at mint with 400.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client mints embed tokens for a single project. Construct one via New and reuse for the lifetime of the process - Client is safe for concurrent use.

func New

func New(projectID, apiKey string, opts ...Option) *Client

New returns a Client bound to projectID, authenticating mint requests with apiKey as a bearer token. The default HTTP client has a 10-second request timeout.

func (*Client) MintToken

func (c *Client) MintToken(ctx context.Context, opts TokenOptions) (string, error)

MintToken requests a new embed token from the API and returns the JWT string on success. Validates options client-side before sending; validation errors short-circuit the round-trip. Server-side 4xx responses are returned as *Error.

type Error

type Error struct {
	StatusCode int
	Body       string
}

Error is returned when the mint endpoint responds with a non-2xx status. Use errors.As to inspect the status code and body.

func (*Error) Error

func (e *Error) Error() string

type Option

type Option func(*Client)

Option configures a Client at construction.

func WithBaseURL

func WithBaseURL(url string) Option

WithBaseURL overrides the default API host. Primarily for tests against httptest.Server and for staging environments. Trailing slashes are trimmed.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient overrides the default *http.Client. Useful for tests (httptest) and for setting custom transports or timeouts.

type TokenOptions

type TokenOptions struct {
	// TenantID, if non-empty, scopes the token's reads to events with
	// a matching tenant_id. The SDK trims the value before sending.
	// Rejected if empty after trim or > 256 chars.
	TenantID string

	// ExpiresIn requests a token lifetime. The server clamps to
	// [MinExpiresIn, MaxExpiresIn]. Zero uses the server default
	// (1 hour).
	ExpiresIn time.Duration

	// AllowedColumns whitelists Event field names (JSON tags) the
	// token's reads return. Nil means no restriction (all fields).
	// An empty non-nil slice is rejected - the server requires
	// explicit nil/omit for "all" to avoid silently widening scope
	// when callers build the list from filtered user input.
	AllowedColumns []string

	// AllowedActions filters reads to events whose action matches any
	// entry. Entries are exact (`user.login`) or suffix wildcards
	// (`user.*`). Nil means no restriction; empty non-nil slice is
	// rejected (same reasoning as AllowedColumns).
	AllowedActions []string

	// AllowedFields restricts which catalog fields the token's
	// DSL queries (and NLP-generated DSL) can reference. Same nil /
	// non-nil-empty semantics as AllowedColumns / AllowedActions.
	// When unset, every catalog field is available.
	AllowedFields []string

	// AllowDSLInput unlocks the Query (advanced DSL) tab in the
	// embed components and accepts `?q=` on the read API. Default
	// false - partner end-users can't type DSL.
	AllowDSLInput bool

	// AllowNLP unlocks the AI ("Ask in plain English") tab in the
	// embed components and POST /v1/embed/events/nlp. Default
	// false.
	AllowNLP bool
}

TokenOptions configures a token mint request. All fields are optional; the zero value mints a 1-hour, full-project, read-only token.