requests

package
v0.27.0-rc.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2026 License: Apache-2.0 Imports: 5 Imported by: 4

Documentation

Overview

Package requests defines structures to represent requests' bodies from API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AcceptInvite 

type AcceptInvite struct {
	TenantID string `param:"tenant" validate:"required"`
	UserID   string `header:"X-ID" validate:"required"`
}

AcceptInvite is the request that turns an invitation into a membership. The invitee is the authenticated caller, so the request carries no email of its own.

type AccessPolicyCreate 

type AccessPolicyCreate struct {
	Name          string              `json:"name" validate:"required"`
	Subject       AccessPolicySubject `json:"subject" validate:"required"`
	Filter        AccessPolicyFilter  `json:"filter"`
	Logins        []string            `json:"logins" validate:"required,min=1,dive,required"`
	SourceIP      []string            `json:"source_ip" validate:"omitempty,dive,cidr|ip"`
	Action        string              `json:"action" validate:"omitempty,oneof=allow deny"`
	RequireReauth bool                `json:"require_reauth" validate:""`
	ReauthPeriod  *int                `json:"reauth_period" validate:"omitempty,gte=0"`
	TenantID      string              `json:"-"`
}

AccessPolicyCreate is the structure to represent the request data for the create access policy endpoint.

type AccessPolicyDelete 

type AccessPolicyDelete struct {
	AccessPolicyIDParam
	TenantID string `json:"-"`
}

AccessPolicyDelete is the structure to represent the request data for the delete access policy endpoint.

type AccessPolicyFilter 

type AccessPolicyFilter struct {
	Tags []string `json:"tags,omitempty"`
}

AccessPolicyFilter selects the devices an access policy applies to, by tags. Empty (or omitted) matches every device.

type AccessPolicyGet 

type AccessPolicyGet struct {
	AccessPolicyIDParam
	TenantID string `json:"-"`
}

AccessPolicyGet is the structure to represent the request data for the get access policy endpoint.

type AccessPolicyIDParam 

type AccessPolicyIDParam struct {
	ID string `param:"id" validate:"required"`
}

AccessPolicyIDParam represents an access policy id as a path param.

type AccessPolicyList 

type AccessPolicyList struct {
	TenantID string `json:"-"`
}

AccessPolicyList is the structure to represent the request data for the list access policies endpoint.

type AccessPolicySubject 

type AccessPolicySubject struct {
	Type  string `json:"type" validate:"required,oneof=user role all-members"`
	Value string `json:"value"`
}

AccessPolicySubject identifies who an access policy grants access to.

type AccessPolicyUpdate 

type AccessPolicyUpdate struct {
	AccessPolicyIDParam
	Name          string              `json:"name" validate:"required"`
	Subject       AccessPolicySubject `json:"subject" validate:"required"`
	Filter        AccessPolicyFilter  `json:"filter"`
	Logins        []string            `json:"logins" validate:"required,min=1,dive,required"`
	SourceIP      []string            `json:"source_ip" validate:"omitempty,dive,cidr|ip"`
	Action        string              `json:"action" validate:"omitempty,oneof=allow deny"`
	RequireReauth bool                `json:"require_reauth" validate:""`
	ReauthPeriod  *int                `json:"reauth_period" validate:"omitempty,gte=0"`
	TenantID      string              `json:"-"`
}

AccessPolicyUpdate is the structure to represent the request data for the update access policy endpoint.

type AuthLocalUser added in v0.18.0 

type AuthLocalUser struct {
	// Identifier represents an username or email.
	//
	// TODO: change json tag from username to identifier and update the OpenAPI.
	Identifier models.UserAuthIdentifier `json:"username" validate:"required"`
	Password   string                    `json:"password" validate:"required"`
}

AuthLocalUser is the structure to represent the request body for the user auth endpoint.

type AuthTokenSwap 

type AuthTokenSwap struct {
	TenantParam
}

AuthTokenSwap is the structure to represent the request data for swap auth token endpoint.

type CancelMembershipInvitation 

type CancelMembershipInvitation struct {
	TenantID      string `param:"tenant" validate:"required"`
	UserID        string `header:"X-ID" validate:"required"`
	InvitedUserID string `param:"uid" validate:"required"`
}

CancelMembershipInvitation is the request to withdraw an invitation the namespace sent. UserID is the caller; InvitedUserID is whose invitation is being withdrawn.

type CreateAPIKey added in v0.15.0 

type CreateAPIKey struct {
	UserID    string          `header:"X-ID"`
	TenantID  string          `header:"X-Tenant-ID"`
	Role      authorizer.Role `header:"X-Role"`
	Name      string          `json:"name" validate:"required,api-key_name"`
	ExpiresAt int             `json:"expires_at" validate:"required,api-key_expires-at"`
	OptRole   authorizer.Role `json:"role" validate:"omitempty,member_role"`
}

CreateAPIKey is the request to mint an API key. UserID, TenantID and Role come from the authenticated caller's headers, not from the body: a caller cannot mint a key more powerful than itself. The key's plaintext is not a field: the server generates it, so no caller can name a secret that another namespace may already hold.

type CreateInstallKey 

type CreateInstallKey struct {
	UserID   string `header:"X-ID"`
	TenantID string `header:"X-Tenant-ID"`
	Name     string `json:"name" validate:"required,api-key_name"`
	// Mode is the enrollment policy. Omitted defaults to "automatic". Mode-specific fields
	// (WebhookURL/WebhookSecret, AllowedIdentities) are validated in the service.
	Mode string `json:"mode" validate:"omitempty,oneof=automatic manual webhook allowlist"`
	// WebhookURL and WebhookSecret configure the webhook mode; AllowedIdentities configures the allowlist mode.
	WebhookURL        string   `json:"webhook_url" validate:"omitempty,url"`
	WebhookSecret     string   `json:"webhook_secret"`
	AllowedIdentities []string `json:"allowed_identities" validate:"omitempty,dive,required"`
	// WebhookTimeout (seconds, max 15) is the synchronous request timeout; WebhookCallbackTTL (seconds,
	// max 24h) is the deferred-decision token's validity. 0/omitted uses the server default.
	WebhookTimeout     int `json:"webhook_timeout" validate:"omitempty,min=0,max=15"`
	WebhookCallbackTTL int `json:"webhook_callback_ttl" validate:"omitempty,min=0,max=86400"`
	// ExpiresIn is how many days from now the key should expire. Nil/omitted means no expiration.
	ExpiresIn *int `json:"expires_in" validate:"omitempty,min=1,max=36500"`
	// UsageLimit caps how many devices may enroll: 1 is single-use (one-off), a higher value is that
	// many devices, 0 (or omitted) is unlimited. Whether the key is reusable is derived from this.
	UsageLimit int  `json:"usage_limit" validate:"omitempty,min=0"`
	Ephemeral  bool `json:"ephemeral"`
	// EphemeralTimeout is how many minutes an ephemeral device may stay offline before removal
	// (1-10). Only honored when Ephemeral is true; defaults to the maximum when omitted.
	EphemeralTimeout int      `json:"ephemeral_timeout" validate:"omitempty,min=1,max=10"`
	Tags             []string `json:"tags" validate:"omitempty,dive,required"`
}

CreateInstallKey is the request to mint an install key. UserID and TenantID come from the caller's headers rather than the body, so a key cannot be minted into another namespace.

type CreateInstanceAPIKey 

type CreateInstanceAPIKey struct {
	Username  string `header:"X-Username"`
	Name      string `json:"name" validate:"required,api-key_name"`
	ExpiresAt int    `json:"expires_at" validate:"required,instance-api-key_expires-at"`
}

CreateInstanceAPIKey is the request to mint an instance API key.

The acting user is identified by username rather than by ID because the admin surface strips X-ID from the request: an admin-panel call carries no user scope.

type CreateTag added in v0.21.0 

type CreateTag struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	Name     string `json:"name" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

CreateTag is the request to add a tag to a namespace's vocabulary, before anything carries it.

type CreateUserToken added in v0.16.0 

type CreateUserToken struct {
	UserID   string `param:"id" header:"X-ID" validate:"required"`
	TenantID string `param:"tenant" validate:"omitempty,uuid"`
}

CreateUserToken is the request to mint a token for a user, optionally scoped to one namespace. With no TenantID the token carries no namespace, which is what a user with no memberships gets.

type DeleteAPIKey added in v0.16.0 

type DeleteAPIKey struct {
	TenantID string `header:"X-Tenant-ID"`
	Name     string `param:"name" validate:"required"`
}

DeleteAPIKey is the request to revoke an API key, addressed by name within the namespace.

type DeleteInstanceAPIKey 

type DeleteInstanceAPIKey struct {
	Name string `param:"name" validate:"required"`
}

DeleteInstanceAPIKey is the request to revoke the named instance API key.

type DeleteTag added in v0.21.0 

type DeleteTag struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	Name     string `param:"name" validate:"required"`
}

DeleteTag is the request to remove a tag from the namespace, detaching it from everything that carries it.

type DeviceAuth 

type DeviceAuth struct {
	Info       *DeviceInfo     `json:"info" validate:"required"`
	Sessions   []string        `json:"sessions,omitempty"`
	Hostname   string          `json:"hostname,omitempty" validate:"required_without=Identity,omitempty,device_name" hash:"-"`
	Identity   *DeviceIdentity `json:"identity,omitempty" validate:"required_without=Hostname,omitempty"`
	PublicKey  string          `json:"public_key" validate:"required"`
	TenantID   string          `json:"tenant_id" validate:"required_without=InstallKey"`
	InstallKey string          `json:"install_key,omitempty"`
	RealIP     string          `header:"X-Real-IP"`
	// ForwardedHost/ForwardedProto carry the public base (set by the gateway) so a webhook-mode
	// enrollment can build an absolute callback URL for the integrator.
	ForwardedHost  string `header:"X-Forwarded-Host"`
	ForwardedProto string `header:"X-Forwarded-Proto"`
}

DeviceAuth is the structure to represent the request data for device auth endpoint.

type DeviceCreateTag 

type DeviceCreateTag struct {
	DeviceParam
	TagBody
}

DeviceCreateTag is the structure to represent the request data for device create tag endpoint.

type DeviceDelete 

type DeviceDelete struct {
	DeviceParam
}

DeviceDelete is the structure to represent the request data for delete device endpoint.

type DeviceDeleteCustomField added in v0.25.0 

type DeviceDeleteCustomField struct {
	TenantID string `header:"X-Tenant-ID"`
	DeviceParam
	Key string `param:"key" validate:"required,min=1,max=64"`
}

DeviceDeleteCustomField is the request to remove one custom key from a device.

type DeviceGet 

type DeviceGet struct {
	DeviceParam
}

DeviceGet is the structure to represent the request data for get device endpoint.

type DeviceIdentity 

type DeviceIdentity struct {
	MAC string `json:"mac"`
}

DeviceIdentity is the hardware identity an agent sends when authenticating. It mirrors models.DeviceIdentity, kept apart so the wire shape can change without moving the stored one.

type DeviceInfo 

type DeviceInfo struct {
	ID         string `json:"id"`
	PrettyName string `json:"pretty_name"`
	Version    string `json:"version"`
	Arch       string `json:"arch"`
	Platform   string `json:"platform"`
}

DeviceInfo is the operating-system description an agent sends when authenticating. It mirrors models.DeviceInfo, kept apart so the wire shape can change without moving the stored one.

type DeviceList added in v0.16.0 

type DeviceList struct {
	TenantID     string              `header:"X-Tenant-ID"`
	DeviceStatus models.DeviceStatus `query:"status"` //  TODO: validate
	query.Paginator
	query.Sorter
	query.Filters
}

DeviceList is the request to page through a namespace's devices. An empty DeviceStatus means every status, not none.

type DeviceLoginCodeResolve 

type DeviceLoginCodeResolve struct {
	Code string `param:"code" validate:"required"`
}

DeviceLoginCodeResolve is the structure to represent the request data for the device login code resolve endpoint.

type DeviceLookup 

type DeviceLookup struct {
	TenantID string `query:"tenant_id" validate:"required"`
	Name     string `query:"name" validate:"required"`
}

DeviceLookup is the structure to represent the request data for lookup device endpoint.

type DeviceOffline 

type DeviceOffline struct {
	DeviceParam
}

DeviceOffline is the structure to represent the request data for offline device endpoint.

type DevicePairingAccept 

type DevicePairingAccept struct {
	Code     string `param:"code" validate:"required"`
	TenantID string `json:"tenant_id" validate:"required,uuid"`
}

DevicePairingAccept is the structure to represent the request data for the device pairing accept endpoint. The code is validated (normalized + checked) in the service, not here, since its charset/length is the pairing-code alphabet, not hexadecimal.

type DevicePairingCreate 

type DevicePairingCreate struct {
	Info      *DeviceInfo     `json:"info" validate:"required"`
	Hostname  string          `json:"hostname,omitempty" validate:"required_without=Identity,omitempty,device_name" hash:"-"`
	Identity  *DeviceIdentity `json:"identity,omitempty" validate:"required_without=Hostname,omitempty"`
	PublicKey string          `json:"public_key" validate:"required"`
	Code      string          `json:"code,omitempty"`
}

DevicePairingCreate is the structure to represent the request data for the device pairing creation endpoint. It mirrors DeviceAuth minus the tenant, which the user chooses at accept time.

Code is optional: when set, the agent was handed a pre-authorized pairing code at install time (see PrepareDevicePairing), so instead of minting a code for a user to accept, the server claims it and accepts the device automatically.

type DevicePairingStatus 

type DevicePairingStatus struct {
	Code string `param:"code" validate:"required"`
}

DevicePairingStatus is the structure to represent the request data for the device pairing status endpoint.

type DeviceParam 

type DeviceParam struct {
	UID string `param:"uid" validate:"required"`
}

DeviceParam is a structure to represent and validate a device UID as path param.

type DeviceRemoveTag 

type DeviceRemoveTag struct {
	DeviceParam
	TagBody
}

DeviceRemoveTag is the structure to represent the request data for device remove tag endpoint.

type DeviceRename 

type DeviceRename struct {
	DeviceParam
	Name string `json:"name" validate:"required"`
}

DeviceRename is the structure to represent the request data for rename device endpoint.

type DeviceSetCustomField added in v0.25.0 

type DeviceSetCustomField struct {
	TenantID string `header:"X-Tenant-ID"`
	DeviceParam
	Key   string `param:"key" validate:"required,min=1,max=64"`
	Value string `json:"value" validate:"max=256"`
}

DeviceSetCustomField is the request to set one custom key/value on a device. Setting an existing key overwrites it, so this is an upsert rather than an insert.

type DeviceUpdate 

type DeviceUpdate struct {
	TenantID string `header:"X-Tenant-ID"`
	UID      string `param:"uid" validate:"required"`
	Name     string `json:"name" validate:"omitempty,device_name"`
}

DeviceUpdate is the request to change a device's editable fields. An omitted field is left alone, which is why Name is optional rather than required.

type DeviceUpdateStatus 

type DeviceUpdateStatus struct {
	TenantID string `header:"X-Tenant-ID"`
	UID      string `param:"uid" validate:"required"`
	Status   string `param:"status" validate:"required"`
}

DeviceUpdateStatus is the request to accept, reject or re-pend a device. The target status is a path parameter, so the same route serves all three transitions.

type DeviceUpdateTag 

type DeviceUpdateTag struct {
	DeviceParam
	Tags []string `json:"tags" validate:"required,min=0,max=3,unique,dive,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

DeviceUpdateTag is the structure to represent the request data for device update tags endpoint.

type EditSSHAccessMode 

type EditSSHAccessMode struct {
	TenantParam
	SSHAccessMode string `json:"ssh_access_mode" validate:"required,oneof=legacy identity"`
}

EditSSHAccessMode is the structure to represent the request data for the edit SSH access mode endpoint.

type EnrollmentCallback 

type EnrollmentCallback struct {
	Token    string `param:"token" validate:"required"`
	Decision string `json:"decision" validate:"required,oneof=accept reject"`
	Reason   string `json:"reason"`
}

EnrollmentCallback is a webhook integrator's deferred decision, redeemed against the signed callback token embedded in the URL. The token is the credential (no API key), so there is no tenant header.

type FingerprintParam 

type FingerprintParam struct {
	Fingerprint string `param:"fingerprint" validate:"required"`
}

FingerprintParam is a structure to represent and validate a public key fingerprint as path param. 

type GenerateInvitationLink struct {
	ForwardedHost  string          `header:"X-Forwarded-Host" validate:"required"`
	ForwardedProto string          `header:"X-Forwarded-Proto"`
	TenantID       string          `param:"tenant" validate:"required,uuid"`
	UserID         string          `header:"X-ID" validate:"required"`
	MemberEmail    string          `json:"email" validate:"required"`
	MemberRole     authorizer.Role `json:"role" validate:"required,member_role"`
}

GenerateInvitationLink is the request to invite an email into a namespace and get back a link. The forwarded headers are what the link's host is built from, so the link points at the address the user reached the console on rather than at the server's own idea of itself.

type GetStats added in v0.21.0 

type GetStats struct {
	TenantID string `header:"X-Tenant-ID"`
}

GetStats is the request for one namespace's dashboard counters.

type GetSystemInfo added in v0.18.0 

type GetSystemInfo struct {
	Host string `header:"X-Forwarded-Host"`
	Port int    `header:"X-Forwarded-Port"`
}

GetSystemInfo is the request behind the unauthenticated info endpoint. The forwarded headers are how the server learns the address clients reach it on, which is what it echoes back as its endpoints.

type LeaveNamespace added in v0.17.1 

type LeaveNamespace struct {
	UserID string `header:"X-ID" validate:"required"`
	// TenantID represents the namespace that the user intends to leave.
	TenantID string `param:"tenant" validate:"required,uuid"`
	// AuthenticatedTenantID represents the namespace to which the user is currently authenticated.
	AuthenticatedTenantID string `header:"X-Tenant-ID" validate:"required"`
}

LeaveNamespace is the request to give up one's own membership. It carries both the namespace being left and the one the caller is authenticated to, because leaving the namespace you are currently in has to invalidate the token you are holding.

type ListAPIKey added in v0.16.0 

type ListAPIKey struct {
	TenantID string `header:"X-Tenant-ID"`
	query.Paginator
	query.Sorter
}

ListAPIKey is the request to page through a namespace's API keys.

type ListInstallKey 

type ListInstallKey struct {
	TenantID string `header:"X-Tenant-ID"`
	query.Paginator
	query.Sorter
}

ListInstallKey is the request to page through a namespace's install keys. It never returns key material — see RevealInstallKey for that.

type ListInstallKeyEvents 

type ListInstallKeyEvents struct {
	TenantID string `header:"X-Tenant-ID"`
	// ID is the install key's digest. History is keyed by digest, not name: names are unique only per
	// namespace and can be reused (the system "legacy" key) or renamed, so a name would be ambiguous.
	ID string `param:"id" validate:"required"`
	query.Paginator
	query.Sorter
}

ListInstallKeyEvents is the request to page through what one install key has enrolled.

type ListInstanceAPIKey 

type ListInstanceAPIKey struct {
	query.Paginator
	query.Sorter
}

ListInstanceAPIKey is the request to list every instance API key.

type ListPublicKeys added in v0.21.0 

type ListPublicKeys struct {
	TenantID string `header:"X-Tenant-ID"`
	query.Paginator
	query.Filters
}

ListPublicKeys is the request to page through the namespace's registered SSH keys.

type ListSessions added in v0.21.0 

type ListSessions struct {
	TenantID string `header:"X-Tenant-ID"`
	query.Paginator
	query.Filters
}

ListSessions is the request to page through a namespace's sessions, live and finished alike.

type ListTags added in v0.21.0 

type ListTags struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	query.Paginator
	query.Filters
	query.Sorter
}

ListTags is the request to page through a namespace's tags.

type MemberList 

type MemberList struct {
	TenantID string `param:"tenant" validate:"required,uuid"`
	query.Paginator
}

MemberList is the structure to represent the request data for the list namespace members endpoint, consistent with the rest of the /namespaces/:tenant family.

type MemberParam 

type MemberParam struct {
	MemberUID string `param:"uid" validate:"required"`
}

MemberParam is a structure to represent and validate a member UID as path param.

type NamespaceAddMember added in v0.16.0 

type NamespaceAddMember struct {
	ForwardedHost  string          `header:"X-Forwarded-Host" validate:"required"`
	ForwardedProto string          `header:"X-Forwarded-Proto"`
	UserID         string          `header:"X-ID" validate:"required"`
	TenantID       string          `param:"tenant" validate:"required,uuid"`
	MemberEmail    string          `json:"email" validate:"required"`
	MemberRole     authorizer.Role `json:"role" validate:"required,member_role"`
}

NamespaceAddMember is the request to invite an email into a namespace with a role. The forwarded headers build the invitation link's host, so it points at the address the inviter reached the console on.

type NamespaceCreate 

type NamespaceCreate struct {
	UserID   string `header:"X-ID" validate:"required"`
	Name     string `json:"name"  validate:"required,hostname_rfc1123,excludes=."`
	TenantID string `json:"tenant" validate:"omitempty,uuid"`
	Type     string `json:"type" validate:"omitempty,lowercase,oneof=personal team"`
}

NamespaceCreate is the structure to represent the request data for create namespace endpoint.

type NamespaceDelete 

type NamespaceDelete struct {
	TenantParam
}

NamespaceDelete is the structure to represent the request data for delete namespace endpoint.

type NamespaceEdit 

type NamespaceEdit struct {
	TenantParam
	Name     string `json:"name" validate:"omitempty,hostname_rfc1123,excludes=."`
	Settings struct {
		SessionRecord          *bool   `json:"session_record" validate:"omitempty"`
		ConnectionAnnouncement *string `json:"connection_announcement" validate:"omitempty,min=0,max=4096"`
	} `json:"settings"`
}

NamespaceEdit is the structure to represent the request data for edit namespace endpoint.

type NamespaceGet 

type NamespaceGet struct {
	TenantParam
}

NamespaceGet is the structure to represent the request data for get namespace endpoint.

type NamespaceList added in v0.17.0 

type NamespaceList struct {
	UserID   string `header:"X-ID"`
	TenantID string `header:"X-Tenant-ID"`
	// IsAdmin comes from the authenticated identity; a client-supplied X-Admin is overwritten.
	IsAdmin bool `header:"X-Admin"`
	query.Paginator
	query.Filters
}

NamespaceList is the structure to represent the request data for list namespaces endpoint.

type NamespaceMembershipInvitationList 

type NamespaceMembershipInvitationList struct {
	// ForwardedHost is only used to build the copyable invite_url; it's optional so a missing
	// header degrades to omitting the link rather than failing the whole listing.
	ForwardedHost  string `header:"X-Forwarded-Host"`
	ForwardedProto string `header:"X-Forwarded-Proto"`
	TenantID       string `param:"tenant" validate:"required"`
	UserID         string `header:"X-ID" validate:"required"`
	query.Paginator
	query.Sorter
	query.Filters
}

NamespaceMembershipInvitationList is the request to page through one namespace's outstanding invitations — the other direction from UserMembershipInvitationList.

type NamespaceRemoveMember added in v0.16.0 

type NamespaceRemoveMember struct {
	UserID   string `header:"X-ID" validate:"required"`
	TenantID string `param:"tenant" validate:"required,uuid"`
	MemberID string `param:"uid" validate:"required"`
}

NamespaceRemoveMember is the request to remove someone else from a namespace. A member removing themselves is LeaveNamespace instead.

type NamespaceUpdateMember added in v0.16.0 

type NamespaceUpdateMember struct {
	UserID     string          `header:"X-ID" validate:"required"`
	TenantID   string          `param:"tenant" validate:"required,uuid"`
	MemberID   string          `param:"uid" validate:"required"`
	MemberRole authorizer.Role `json:"role" validate:"omitempty,member_role"`
}

NamespaceUpdateMember is the request to change a member's role. UserID is the caller, MemberID the member being changed — a caller cannot grant a role above their own.

type OptionalInt 

type OptionalInt struct {
	Present bool
	Value   *int
}

OptionalInt carries RFC 7396 (JSON Merge Patch) semantics for a nullable integer field in a partial update: an omitted key leaves the value unchanged (Present is false), an explicit null clears it (Present is true, Value is nil), and a number sets it.

func (*OptionalInt) UnmarshalJSON 

func (o *OptionalInt) UnmarshalJSON(data []byte) error

UnmarshalJSON records that the key was present, which is the whole point of the type: it runs only when the key appears, so an omitted key leaves the zero value and reads as "unchanged".

type PublicKeyAuth 

type PublicKeyAuth struct {
	Fingerprint string `json:"fingerprint" validate:"required"`
	Data        string `json:"data" validate:"required"`
}

PublicKeyAuth is the structure to represent the request data for public key auth endpoint.

type PublicKeyCreate 

type PublicKeyCreate struct {
	Data        []byte          `json:"data" validate:"required"`
	Filter      PublicKeyFilter `json:"filter" validate:"required"`
	Name        string          `json:"name" validate:"required"`
	Username    string          `json:"username" validate:"required,regexp"`
	TenantID    string          `json:"-"`
	Fingerprint string          `json:"-"`
}

PublicKeyCreate is the structure to represent the request data for create public key endpoint.

type PublicKeyDelete 

type PublicKeyDelete struct {
	FingerprintParam
}

PublicKeyDelete is the structure to represent the request data for delete public key endpoint.

type PublicKeyFilter 

type PublicKeyFilter struct {
	Hostname string   `json:"hostname,omitempty" validate:"required_without=Tags,excluded_with=Tags,regexp"`
	Tags     []string `json:"tags,omitempty" validate:"required_without=Hostname"`
}

PublicKeyFilter is the device selector attached to a key: either a hostname pattern or a tag set, never both. It mirrors models.PublicKeyFilter, kept apart so the wire shape can change without moving the stored one.

type PublicKeyGet 

type PublicKeyGet struct {
	FingerprintParam
	TenantParam
}

PublicKeyGet is the structure to represent the request data for get public key endpoint.

type PublicKeyTagAdd 

type PublicKeyTagAdd struct {
	FingerprintParam
	TagParam
}

PublicKeyTagAdd is the structure to represent the request data for add tag to public key endpoint.

type PublicKeyTagRemove 

type PublicKeyTagRemove struct {
	FingerprintParam
	TagParam
}

PublicKeyTagRemove is the structure to represent the request data for remove tag from public key endpoint.

type PublicKeyTagsUpdate 

type PublicKeyTagsUpdate struct {
	FingerprintParam
	Tags []string `json:"tags" validate:"required,min=1,max=3,unique,dive,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

PublicKeyTagsUpdate is the structure to represent the request data for update tags from public key endpoint.

type PublicKeyUpdate 

type PublicKeyUpdate struct {
	FingerprintParam
	// Name is the public key's name.
	Name string `json:"name" validate:"required"`
	// Username is the public key's username.
	Username string `json:"username" validate:"required,regexp"`
	// Filter is the public key's filter.
	Filter PublicKeyFilter `json:"filter" validate:"required"`
}

PublicKeyUpdate is the structure to represent the request data for update public key endpoint.

type PullTag added in v0.21.0 

type PullTag struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	Name     string `param:"name" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
	// TargetID is the identifier of the target to pull the tag of.
	// For the reason cannot of it can be a list of things (UID for device, ID for firewall, etc...), it
	// cannot be parsed and must be set manually
	TargetID string `validate:"required"`
}

PullTag is the request to detach a tag from one target. The tag itself survives.

type PushTag added in v0.21.0 

type PushTag struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	Name     string `param:"name" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
	// TargetID is the identifier of the target to push the tag on.
	// For the reason cannot of it can be a list of things (UID for device, ID for firewall, etc...), it
	// cannot be parsed and must be set manually
	TargetID string `validate:"required"`
}

PushTag is the request to attach an existing tag to one target.

type RegisterUser 

type RegisterUser struct {
	Name     string `json:"name" validate:"required,name"`
	Username string `json:"username" validate:"required,username"`
	// Email is required for open self-registration, but omitted on the invite flow:
	// there the email is derived from the invitation the Sig resolves to (the invitee
	// can't retarget it), so it's optional when a Sig is present.
	Email          string `json:"email" validate:"required_without=Sig,omitempty,email"`
	Password       string `json:"password" validate:"required,password"`
	EmailMarketing bool   `json:"email_marketing"`

	// Sig is the invitation code from the accept-invite link. When present, it proves
	// the email was already validated (the invitee clicked the link) and identifies the
	// invitation. It's a human-readable pairing code, not a UUID.
	Sig string `json:"sig" validate:"omitempty"`
}

RegisterUser is the request to create an account, serving both open sign-up and the invite flow. Which one it is follows from Sig: with an invitation code the email comes from the invitation rather than the body, so the invitee cannot point it somewhere else.

type ResolveDevice added in v0.19.1 

type ResolveDevice struct {
	TenantID string `header:"X-Tenant-ID" validate:"required"`
	UID      string `query:"uid" validate:"omitempty"`
	Hostname string `query:"hostname" validate:"omitempty"`
}

ResolveDevice is the request to find a device by UID or by hostname. Exactly one of the two is meant to be set; both are optional here because which one is present is the caller's choice.

type ResolveInvitation 

type ResolveInvitation struct {
	Invite string `query:"invite" validate:"required"`
}

ResolveInvitation resolves a pending invitation from its invite code alone — the only thing the accept-invite link carries. Public: the code is the credential.

type RevealInstallKey 

type RevealInstallKey struct {
	TenantID string `header:"X-Tenant-ID"`
	Name     string `param:"name" validate:"required"`
}

RevealInstallKey is the request to read back an install key's secret. It is the only route that returns one, which is why it is separate from the listing.

type RoleBody 

type RoleBody struct {
	Role string `json:"role" validate:"required,oneof=administrator operator observer"`
}

RoleBody is a structure to represent and validate a namespace role as request body.

type SSHApprovalConfirm 

type SSHApprovalConfirm struct {
	Code string `param:"code" validate:"required"`
	// ExpiresIn is how many days the key being bound should keep working,
	// omitted for a key that never expires. Only meaningful for the identity
	// kind, since a re-auth binds nothing.
	ExpiresIn *int `json:"expires_in" validate:"omitempty,min=1"`
}

SSHApprovalConfirm is the request data for the accept endpoint.

type SSHApprovalCreate 

type SSHApprovalCreate struct {
	SessionUID string `json:"session_uid" validate:"required"`
	SSHID      string `json:"sshid" validate:"required"`
	TenantID   string `json:"tenant_id" validate:"required,uuid"`
	DeviceUID  string `json:"device_uid" validate:"required"`
	DeviceName string `json:"device_name" validate:""`
	Username   string `json:"username" validate:"required"`
	IPAddress  string `json:"ip_address" validate:"required"`
	// Kind is what confirming will do: bind the key as an identity, or refresh an
	// existing identity's re-auth window.
	Kind        models.SSHApprovalKind `json:"kind" validate:"required,oneof=identity reauth"`
	Fingerprint string                 `json:"fingerprint" validate:"required"`
	Data        []byte                 `json:"data" validate:"required"`
	// ReauthPeriod carries the policy's window so the console can say how long
	// confirming lasts. Only meaningful for the reauth kind.
	ReauthPeriod *int `json:"reauth_period" validate:""`
}

SSHApprovalCreate is the payload the SSH gateway posts to open a JIT login approval. The gateway only posts it once it knows a browser step is actually needed, so the presented key and the kind come with it. It has already resolved the target device and namespace, so it passes them through; the API does not re-parse the SSHID.

type SSHApprovalGet 

type SSHApprovalGet struct {
	Code string `param:"code" validate:"required"`
}

SSHApprovalGet is the request data for the endpoint the console page uses to render the approval request details.

type SSHApprovalReject 

type SSHApprovalReject struct {
	Code string `param:"code" validate:"required"`
}

SSHApprovalReject is the request data for the deny endpoint.

type SSHApprovalStatus 

type SSHApprovalStatus struct {
	Code string `param:"code" validate:"required"`
	// Wait asks the API to hold the request open until the login is decided
	// instead of answering "pending" right away. The gateway sets it so the
	// person is not left staring at a frozen terminal for a poll interval after
	// they already decided.
	Wait bool `query:"wait" validate:""`
}

SSHApprovalStatus is the request data for the status endpoint the gateway polls. The code is validated (normalized + checked) in the service.

type SSHIdentityCreate 

type SSHIdentityCreate struct {
	TenantID string `json:"-"`
	UserID   string `json:"-"`
	Name     string `json:"name" validate:""`
	// Data is the OpenSSH public key to enroll.
	Data string `json:"data" validate:"required"`
	// Source says whether this is a key somebody pasted or the web terminal
	// enrolling its own browser-held one, defaulting to the former. The caller
	// asserts it, so it may only ever label the identity — the approval path is
	// not accepted here precisely because that one the server knows for itself.
	Source models.SSHIdentitySource `json:"source" validate:"omitempty,oneof=manual browser"`
	// ExpiresIn is how many days the key should keep working, omitted for a key
	// that never expires. The gateway refuses a login with an expired key.
	ExpiresIn *int `json:"expires_in" validate:"omitempty,min=1"`
}

SSHIdentityCreate is the request data for manually enrolling an SSH public key (paste a key in the console) as an identity for the caller.

type SSHIdentityDelete 

type SSHIdentityDelete struct {
	SSHIdentityIDParam
	TenantID string `json:"-"`
	UserID   string `json:"-"`
	// Manage reports whether the caller holds the SSHIdentityManage permission,
	// allowing them to revoke another member's identity.
	Manage bool `json:"-"`
}

SSHIdentityDelete is the request data for revoking an enrolled SSH identity.

type SSHIdentityIDParam 

type SSHIdentityIDParam struct {
	ID string `param:"id" validate:"required"`
}

SSHIdentityIDParam represents an SSH identity id as a path param.

type SSHIdentityList 

type SSHIdentityList struct {
	TenantID      string `json:"-"`
	UserID        string `json:"-"`
	AllPrincipals bool   `json:"-" query:"-"`
}

SSHIdentityList is the request data for listing enrolled SSH identities in the current namespace. AllPrincipals widens the listing from the caller's own identities to every member's; the handler sets it from the caller's permissions, so it is never read from the request and a client cannot ask for a scope it does not hold.

type SSHIdentityUpdate 

type SSHIdentityUpdate struct {
	SSHIdentityIDParam
	TenantID string `json:"-"`
	UserID   string `json:"-"`
	Name     string `json:"name" validate:"required"`
}

SSHIdentityUpdate is the request data for renaming an enrolled SSH identity.

type ServiceAccountCreate 

type ServiceAccountCreate struct {
	TenantID string `json:"-"`
	Name     string `json:"name" validate:"required"`
	// Data is the OpenSSH public key to enroll for the service account.
	Data string `json:"data" validate:"required"`
	// SingleUse burns the key after one established SSH session (Vault-OTP style:
	// consumed per access, not per enrollment).
	SingleUse bool `json:"single_use"`
	// ExpiresIn is the key's TTL in days from creation; nil means it never
	// expires. Service-account only.
	ExpiresIn *int `json:"expires_in" validate:"omitempty,min=1"`
}

ServiceAccountCreate is the request data for creating a service account: a display name plus the OpenSSH public key to enroll as its first identity.

type ServiceAccountDelete 

type ServiceAccountDelete struct {
	ServiceAccountIDParam
	TenantID string `json:"-"`
}

ServiceAccountDelete is the request data for deleting a service account. Removing the account cascades to its membership and every SSH identity it holds.

type ServiceAccountIDParam 

type ServiceAccountIDParam struct {
	ID string `param:"id" validate:"required"`
}

ServiceAccountIDParam represents a service account id as a path param.

type ServiceAccountList 

type ServiceAccountList struct {
	TenantID string `json:"-"`
}

ServiceAccountList is the request data for listing a namespace's service accounts.

type SessionAuthenticatedSet 

type SessionAuthenticatedSet struct {
	SessionIDParam
	Authenticated bool `json:"authenticated" validate:"required"`
}

SessionAuthenticatedSet is the structure to represent the request data for set authenticated session endpoint.

type SessionCreate 

type SessionCreate struct {
	UID       string `json:"uid" validate:"required"`
	DeviceUID string `json:"device_uid" validate:"required"`
	Username  string `json:"username" validate:"required"`
	IPAddress string `json:"ip_address" validate:"required"`
	Type      string `json:"type" validate:"required"`
	Term      string `json:"term" validate:""`
	Web       bool   `json:"web" validate:""`
	// UserID is the ShellHub account that authorized the session via browser
	// approval. Empty for password/public-key and web-terminal sessions.
	UserID string `json:"user_id" validate:""`
}

SessionCreate is the structure to represent the request data for create session endpoint.

type SessionEditRecordStatus 

type SessionEditRecordStatus struct {
	TenantParam
	SessionRecord bool `json:"session_record"`
}

SessionEditRecordStatus is the structure to represent the request data for edit session record status endpoint.

type SessionEvent added in v0.18.0 

type SessionEvent struct {
	Type      string    `json:"type" validate:"required"`
	Timestamp time.Time `json:"timestamp" validate:"required"`
	Data      any       `json:"data" validate:"required"`
	Seat      int       `json:"seat" validate:"min=0"`
}

SessionEvent is one recorded event within a session. Data's shape follows Type, and Seat says which of a multiplexed session's terminals it came from.

type SessionFinish 

type SessionFinish struct {
	SessionIDParam
}

SessionFinish is the structure to represent the request data for finish session endpoint.

type SessionGet 

type SessionGet struct {
	SessionIDParam
}

SessionGet is the structure to represent the request data for get session endpoint.

type SessionIDParam 

type SessionIDParam struct {
	// UID is the session's UID.
	UID string `param:"uid" validate:"required"`
}

SessionIDParam is a structure to represent and validate a session UID as path param.

type SessionKeepAlive 

type SessionKeepAlive struct {
	SessionIDParam
}

SessionKeepAlive is the request an active session sends to stay marked live. Missing them is what eventually marks a session inactive.

type SessionSeat added in v0.19.0 

type SessionSeat struct {
	SessionIDParam
	ID int `json:"id"`
}

SessionSeat addresses one terminal within a session, which is how a single SSH connection can carry more than one.

type SessionUpdate added in v0.16.0 

type SessionUpdate struct {
	SessionIDParam
	Recorded      *bool   `json:"recorded"`
	Authenticated *bool   `json:"authenticated"`
	Type          *string `json:"type"`
}

SessionUpdate is a partial update to a live session: a nil field is left alone.

type Setup 

type Setup struct {
	Email     string `json:"email" validate:"required,email"`
	Name      string `json:"name" validate:"required,name"`
	Username  string `json:"username" validate:"required,username"`
	Password  string `json:"password" validate:"required,password"`
	Namespace string `json:"namespace" validate:"required,hostname_rfc1123,excludes=."`
}

Setup is the request that initialises a fresh instance: it creates the first user and their namespace in one step. It is refused once an instance is set up, so it runs at most once.

type SystemInstallScript 

type SystemInstallScript struct {
	Host              string `header:"X-Forwarded-Host"`
	Scheme            string `header:"X-Forwarded-Proto"`
	ForwardedPort     string `header:"X-Forwarded-Port"`
	TenantID          string `query:"tenant_id" validate:"omitempty,uuid"`
	PreferredHostname string `query:"preferred_hostname" validate:"omitempty,device_name"`
	PreferredIdentity string `query:"preferred_identity" validate:"omitempty,device_identity"`
}

SystemInstallScript is the request behind the install script an operator pipes into a shell. The forwarded headers become the server address baked into the script, and the query parameters become the agent's flags. A query parameter outside the shape its name implies is rejected rather than rendered, so the caller gets a 400 instead of a script.

type TagBody 

type TagBody struct {
	Tag string `json:"tag" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

TagBody is a structure to represent and validate a tag as json request body.

type TagDelete 

type TagDelete struct {
	TagParam
}

TagDelete is the structure to represent the request data for delete tag endpoint.

type TagParam 

type TagParam struct {
	Tag string `param:"tag" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

TagParam is a structure to represent and validate a tag as path param.

type TagRename 

type TagRename struct {
	TagParam
	NewTag string `json:"tag" validate:"required,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

TagRename is the structure to represent the request data for rename tag endpoint.

type TenantParam 

type TenantParam struct {
	Tenant string `param:"tenant" validate:"required,uuid"`
}

TenantParam is a structure to represent and validate a namespace tenant as path param.

type UpdateAPIKey added in v0.16.0 

type UpdateAPIKey struct {
	UserID   string `header:"X-ID"`
	TenantID string `header:"X-Tenant-ID"`
	// CurrentName is the current stored name. It is different from [UpdateAPIKey.Name], which is used
	// to handle the new target name (optional).
	CurrentName string          `param:"name" validate:"required"`
	Name        string          `json:"name" validate:"omitempty,api-key_name"`
	Role        authorizer.Role `json:"role" validate:"omitempty,member_role"`
}

UpdateAPIKey is the request to rename an API key or change its role. The key is addressed by its current name in the path, so a rename reads both names at once.

type UpdateInstallKey 

type UpdateInstallKey struct {
	UserID   string `header:"X-ID"`
	TenantID string `header:"X-Tenant-ID"`
	// CurrentName is the current stored name (path param). It differs from [UpdateInstallKey.Name],
	// which is the optional new target name.
	CurrentName string `param:"name" validate:"required"`
	Name        string `json:"name" validate:"omitempty,api-key_name"`
	// Mode changes the enrollment policy. Nil leaves it unchanged. Mode-specific fields are validated
	// in the service against the resulting key state.
	Mode *string `json:"mode" validate:"omitempty,oneof=automatic manual webhook allowlist"`
	// WebhookURL/WebhookSecret update the webhook config; nil leaves each unchanged. AllowedIdentities
	// replaces the allowlist when non-nil.
	WebhookURL        *string  `json:"webhook_url" validate:"omitempty,url"`
	WebhookSecret     *string  `json:"webhook_secret"`
	AllowedIdentities []string `json:"allowed_identities" validate:"omitempty,dive,required"`
	// WebhookTimeout/WebhookCallbackTTL update the webhook tuning; nil leaves each unchanged.
	WebhookTimeout     *int `json:"webhook_timeout" validate:"omitempty,min=0,max=15"`
	WebhookCallbackTTL *int `json:"webhook_callback_ttl" validate:"omitempty,min=0,max=86400"`
	// Revoked toggles revocation. Only a false->true transition is honored; un-revoking is rejected.
	Revoked *bool `json:"revoked"`
	// Disabled toggles the reversible pause. Both true and false are honored, so a disabled key can
	// be re-enabled (unlike Revoked).
	Disabled *bool `json:"disabled"`
	// ExpiresIn sets a new expiration as days from now. RFC 7396: omitted leaves the current expiry
	// unchanged, null clears it (never expires), a positive integer sets it.
	ExpiresIn OptionalInt `json:"expires_in"`
	// UsageLimit sets a new enrollment cap (0 unlimited, 1 single-use, N devices). Nil leaves it
	// untouched. Reusability is re-derived from it.
	UsageLimit *int     `json:"usage_limit" validate:"omitempty,min=0"`
	Tags       []string `json:"tags" validate:"omitempty,dive,required"`
	// Ephemeral toggles whether devices enrolled with the key are auto-removed after staying offline
	// past the timeout; nil leaves it unchanged. EphemeralTimeout (1-10 minutes) is only honored when
	// Ephemeral is true.
	Ephemeral        *bool `json:"ephemeral"`
	EphemeralTimeout *int  `json:"ephemeral_timeout" validate:"omitempty,min=1,max=10"`
}

UpdateInstallKey is a partial update: a nil field is left unchanged, which is why the nullable ones are pointers and OptionalInt. The key is addressed by its current name in the path, so a rename reads both names at once.

type UpdateTag added in v0.21.0 

type UpdateTag struct {
	TenantID string `param:"tenant" header:"X-Tenant-ID" validate:"required,uuid"`
	Name     string `param:"name" validate:"required"`
	// Similar to [UpdateTag.Name], but is used to update the tag's name instead of retrieve the tag.
	NewName string `json:"name" validate:"omitempty,min=3,max=255,alphanum,ascii,excludes=/@&:"`
}

UpdateTag is the request to rename a tag. Everything carrying it follows the rename, since targets reference the tag by id.

type UpdateUser added in v0.16.0 

type UpdateUser struct {
	UserID        string `header:"X-ID" validate:"required"`
	Name          string `json:"name" validate:"omitempty,name"`
	Username      string `json:"username" validate:"omitempty,username"`
	Email         string `json:"email" validate:"omitempty,email"`
	RecoveryEmail string `json:"recovery_email" validate:"omitempty,email"`
	// Password is the new password. If not empty, [UserDataUpdate.CurrentPassword] must be the current user's password.
	Password        string `json:"password" validate:"omitempty,password"`
	CurrentPassword string `json:"current_password"`
}

UpdateUser is the structure to represent the request body of the update user data endpoint.

type UserMembershipInvitationList 

type UserMembershipInvitationList struct {
	UserID string `header:"X-ID"`
	query.Paginator
	query.Sorter
	query.Filters
}

UserMembershipInvitationList is the request to page through the invitations addressed to the authenticated user, across every namespace.

type UserPasswordUpdate 

type UserPasswordUpdate struct {
	UserID          string `header:"X-ID" validate:"required"`
	CurrentPassword string `json:"current_password" validate:"required,min=5,max=32,nefield=NewPassword"`
	NewPassword     string `json:"new_password" validate:"required,password,nefield=CurrentPassword"`
}

UserPasswordUpdate is the structure to represent the request body for the update user password endpoint.

type WebReauthVerify 

type WebReauthVerify struct {
	TenantID string `json:"-"`
	UserID   string `json:"-"`
	Password string `json:"password"`
	Code     string `json:"code"`
	// Fingerprint is the SSH identity being re-authenticated. Its freshness is
	// stamped on that identity's last_reauth_at, and it must belong to the caller.
	Fingerprint string `json:"fingerprint" validate:"required"`
	// ApprovalCode is the login waiting on this step-up. Present when a held login
	// should be released by the same call that proves the factor, so verifying and
	// releasing cannot drift apart. Distinct from Code, which is the TOTP.
	ApprovalCode string `json:"approval_code"`
}

WebReauthVerify is the step-up payload for an SSH login's require_reauth gate. TenantID/UserID are set server-side from the gateway-injected headers, never the body. Community validates Password; the enterprise overlay validates Code (TOTP) when the user has MFA.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.