auth

Documentation

Overview

Package auth holds the authentication contract for the SDK.

Two credentials are supported:

• APIKey: a developer API key issued by the vxcloud dashboard, prefixed "xc_dev_" / "xc_test_" / "xc_live_". Exchanged for a JWT on first call.
• Token: an existing JWT pair (access + refresh) — useful when the SDK is embedded in a process that has already authenticated by other means.

The contract matches what FastAPI accepts on the backend today, so this SDK does not require any server-side change to be useful.

Index

• Variables
• type APIKey
  • func (k APIKey) Environment() string
  • func (k APIKey) Validate() error
• type Doer
• type ExchangeResponse
  • func Exchange(ctx context.Context, doer Doer, infinityURL, apiKey, username string) (*ExchangeResponse, error)
• type State
• type Token
  • func (t Token) IsExpired() bool
• type User

Variables

var ErrInvalidKey = errors.New("auth: invalid api key")

ErrInvalidKey is returned when the API key is malformed or rejected.

Types

type APIKey

type APIKey string

APIKey is a developer API key.

func (APIKey) Environment

func (k APIKey) Environment() string

Environment returns "dev", "test", or "live" for a well-formed key.

func (APIKey) Validate

func (k APIKey) Validate() error

Validate reports whether the key has the expected shape. It does NOT contact the server — the network check happens during the exchange call.

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer is the minimal HTTP client interface needed for an exchange call. *http.Client satisfies it.

type ExchangeResponse

type ExchangeResponse struct {
	Access  string `json:"access"`
	Refresh string `json:"refresh"`
	KeyName string `json:"key_name"`
	User    struct {
		Username     string `json:"username"`
		Email        string `json:"email"`
		Organization *struct {
			Name string `json:"name"`
		} `json:"organization,omitempty"`
		Workspace *struct {
			Name string `json:"name"`
		} `json:"workspace,omitempty"`
	} `json:"user"`
}

ExchangeResponse is the wire shape of POST /api/v1/auth/developer/keys/login.

func Exchange

func Exchange(ctx context.Context, doer Doer, infinityURL, apiKey, username string) (*ExchangeResponse, error)

Exchange trades an API key for a JWT pair against the Infinity control plane. Endpoint: POST {infinityURL}/api/v1/auth/developer/keys/login.

Returns the parsed response, including resolved Username / Organization / Workspace from the server (callers can omit username on input — the server identifies the key holder).

type State

type State struct {
	APIKey APIKey
	Token  Token
	User   User
	// NodeURL is the per-tenant node base URL resolved during exchange.
	NodeURL string
}

State is the in-memory authentication state held by the Client. It is concurrency-safe via the surrounding sync.RWMutex in client.go.

type Token

type Token struct {
	Access    string    `json:"access"`
	Refresh   string    `json:"refresh"`
	IssuedAt  time.Time `json:"issued_at,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"`
}

Token is a JWT pair returned by the Infinity control plane.

func (Token) IsExpired

func (t Token) IsExpired() bool

IsExpired returns true when the access token is past its expiration with a small safety margin. Zero ExpiresAt is treated as not-expired (caller will discover via 401).

type User

type User struct {
	Username     string `json:"username"`
	Email        string `json:"email,omitempty"`
	Organization string `json:"organization,omitempty"`
	Workspace    string `json:"workspace,omitempty"`
}

User describes the authenticated principal. Populated from the API key exchange response.