requests

package
v0.30.2 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 4 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 APIKeySSHIdentityCreate added in v0.27.0

type APIKeySSHIdentityCreate struct {
	// KeyName is the API key the identity belongs to.
	KeyName  string `param:"name" json:"-" validate:"required"`
	TenantID string `json:"-"`
	Name     string `json:"name" validate:""`
	// Data is the OpenSSH public key to enroll.
	Data string `json:"data" validate:"required"`
	// ExpiresIn is how many days the key should keep working, omitted for a key that never
	// expires.
	ExpiresIn *int `json:"expires_in" validate:"omitempty,min=1"`
	// SingleUse burns the identity once a session has been established with it, which is what
	// a one-shot job wants: upload a key, connect, and leave nothing reusable behind.
	SingleUse bool `json:"single_use"`
	// CallerAPIKeyID is the id of the API key the request authenticated with, empty for a
	// person. The handler sets it, and the service refuses a key that names another key, so
	// a leaked key can rotate its own credential and plant none.
	CallerAPIKeyID string `json:"-"`
}

APIKeySSHIdentityCreate is the request data for enrolling an SSH public key that an API key owns rather than a person. The key is addressed by name, which is the published convention for its routes; the identity is stored against the key's id, so a later rename does not move what the key owns.

type APIKeySSHIdentityList added in v0.27.0

type APIKeySSHIdentityList struct {
	// KeyName is the API key whose credentials are listed.
	KeyName  string `param:"name" json:"-" validate:"required"`
	TenantID string `json:"-"`
	// CallerAPIKeyID is the id of the API key the request authenticated with, empty for a
	// person. The handler sets it, and the service refuses a key that names another key.
	CallerAPIKeyID string `json:"-"`
}

APIKeySSHIdentityList is the request data for listing the SSH identities an API key owns.

type AcceptInvite added in v0.27.0

type AcceptInvite struct {
	TenantID string `param:"tenant" json:"-" validate:"required"`
	UserID   string `identity:"id" json:"-" validate:"required"`
	Code     string `json:"code" 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. Code is the invite code from the invitation link: being the account an invitation names does not, alone, admit the caller.

type AccessPolicyCreate added in v0.27.0

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 added in v0.27.0

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

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

type AccessPolicyFilter added in v0.27.0

type AccessPolicyFilter struct {
	All  bool     `json:"all"`
	Tags []string `json:"tags" validate:"max=3"`
}

AccessPolicyFilter selects the devices an access policy applies to: every device when All is set, or the devices carrying any of Tags. More than three tags fails validation; the service refuses a filter that gives neither, or both.

type AccessPolicyGet added in v0.27.0

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

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

type AccessPolicyIDParam added in v0.27.0

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

AccessPolicyIDParam represents an access policy id as a path param.

type AccessPolicySubject added in v0.27.0

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

AccessPolicySubject identifies who an access policy grants access to.

type AccessPolicyUpdate added in v0.27.0

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 CancelMembershipInvitation added in v0.27.0

type CancelMembershipInvitation struct {
	TenantID      string `param:"tenant" json:"-" validate:"required"`
	UserID        string `identity:"id" json:"-" validate:"required"`
	InvitedUserID string `param:"uid" json:"-" 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 {
	TenantID  string          `identity:"tenant" json:"-"`
	Role      authorizer.Role `identity:"role" json:"-"`
	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. TenantID and Role come from the caller's authenticated identity, 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 CreateInstanceAPIKey added in v0.27.0

type CreateInstanceAPIKey struct {
	AdminID   string `identity:"admin_id" json:"-" validate:"required"`
	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 administrator is identified by the identity's AdminID rather than its ID because the admin surface strips the ID: an admin-panel call carries no user scope. A request without it is refused, since it names no administrator to record as the key's creator.

type CreateProvisioningKey added in v0.27.0

type CreateProvisioningKey struct {
	TenantID string `identity:"tenant" json:"-"`
	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"`
}

CreateProvisioningKey is the request to mint a provisioning key. TenantID comes from the caller's authenticated identity rather than the body, so a key cannot be minted into another namespace.

type CreateTag added in v0.21.0

type CreateTag struct {
	TenantID string `identity:"tenant" json:"-" 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 DeleteAPIKey added in v0.16.0

type DeleteAPIKey struct {
	TenantID string `identity:"tenant" json:"-"`
	Name     string `param:"name" json:"-" validate:"required"`
}

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

type DeleteInstanceAPIKey added in v0.27.0

type DeleteInstanceAPIKey struct {
	Name string `param:"name" json:"-" 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 `identity:"tenant" json:"-" validate:"required,uuid"`
	Name     string `param:"name" json:"-" 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=ProvisioningKey"`
	ProvisioningKey string          `json:"provisioning_key,omitempty"`
	Challenge       string          `json:"challenge,omitempty" validate:"omitempty,max=128"`
	Signature       string          `json:"signature,omitempty" validate:"omitempty,max=4096"`
}

DeviceAuth is the structure to represent the request data for device auth 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 `identity:"tenant" json:"-"`
	DeviceParam
	Key string `param:"key" json:"-" 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              `identity:"tenant" json:"-"`
	DeviceStatus models.DeviceStatus `query:"status" json:"-" validate:"omitempty,oneof=accepted pending rejected removed unused"`
	Connector    bool                `query:"connector" json:"-" xml:"-"`
	query.Paginator
	query.CursorPaginator
	query.Sorter
	query.Filters
}

DeviceList is the request to page through a namespace's devices. An empty DeviceStatus means every status, not none. A true Connector selects the devices whose platform is connector, and false selects those whose platform is not; no Filters widen the selection past it. Connector binds only from the query, never the body. Paginator and Sorter serve page mode and CursorPaginator serves cursor mode; which one a request is in is decided by which query parameters it carries, since a zero value cannot tell an absent parameter from a zero one.

type DeviceLocationList added in v0.30.0

type DeviceLocationList struct {
	query.Filters
}

DeviceLocationList is the request for the device map: the namespace's accepted devices counted by position, narrowed by the same filter the device list takes.

type DeviceLoginCodeResolve added in v0.27.0

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

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

type DevicePairingAccept added in v0.27.0

type DevicePairingAccept struct {
	Code     string `param:"code" json:"-" 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 added in v0.27.0

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"`
}

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.

type DevicePairingStatus added in v0.27.0

type DevicePairingStatus struct {
	Code string `param:"code" json:"-" 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" json:"-" validate:"required"`
}

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

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 `identity:"tenant" json:"-"`
	DeviceParam
	Key   string `param:"key" json:"-" 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 `identity:"tenant" json:"-"`
	UID      string `param:"uid" json:"-" 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 `identity:"tenant" json:"-"`
	UID      string `param:"uid" json:"-" validate:"required"`
	Status   string `param:"status" json:"-" 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 Empty added in v0.30.0

type Empty struct{}

Empty is the request of a route that takes no input.

type EnrollmentCallback added in v0.27.0

type EnrollmentCallback struct {
	Token    string `param:"token" json:"-" 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" json:"-" validate:"required"`
}

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

type GenerateInvitationLink struct {
	TenantID    string          `param:"tenant" json:"-" validate:"required,uuid"`
	UserID      string          `identity:"id" json:"-" 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 under the instance's public URL.

type LeaveNamespace added in v0.17.1

type LeaveNamespace struct {
	UserID string `identity:"id" json:"-" validate:"required"`
	// TenantID represents the namespace that the user intends to leave.
	TenantID string `param:"tenant" json:"-" validate:"required,uuid"`
	// AuthenticatedTenantID represents the namespace to which the user is currently authenticated.
	AuthenticatedTenantID string `identity:"tenant" json:"-" validate:"required"`
	// TokenVersion is the version of the caller's bearer, which the token minted on leaving the
	// authenticated namespace carries. Nil mints at the user's current version. The handler fills
	// it from the authentication step; no client input reaches it.
	TokenVersion *int `json:"-"`
	// Impersonated keeps the token minted on leaving marked as an instance administrator's, when
	// the caller's bearer was. The handler fills it from the authentication step; no client input
	// reaches it.
	Impersonated bool `json:"-"`
}

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 `identity:"tenant" json:"-"`
	query.Paginator
	query.Sorter
}

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

type ListInstanceAPIKey added in v0.27.0

type ListInstanceAPIKey struct {
	query.Paginator
	query.Sorter
}

ListInstanceAPIKey is the request to list every instance API key.

type ListProvisioningKey added in v0.27.0

type ListProvisioningKey struct {
	TenantID string `identity:"tenant" json:"-"`
	query.Paginator
	query.Sorter
}

ListProvisioningKey is the request to page through a namespace's provisioning keys. It never returns key material — see RevealProvisioningKey for that.

type ListProvisioningKeyEvents added in v0.27.0

type ListProvisioningKeyEvents struct {
	TenantID string `identity:"tenant" json:"-"`
	// ID is the provisioning 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" json:"-" validate:"required"`
	query.Paginator
	query.Sorter
	Filters query.Filters `json:"-"`
}

ListProvisioningKeyEvents is the request to page through what one provisioning key has enrolled.

type ListPublicKeys added in v0.21.0

type ListPublicKeys struct {
	TenantID string `identity:"tenant" json:"-"`
	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 `identity:"tenant" json:"-"`
	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 `identity:"tenant" json:"-" validate:"required,uuid"`
	query.Paginator
	query.Filters
	query.Sorter
}

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

type ListTenantRegistrations added in v0.27.0

type ListTenantRegistrations struct {
	TenantID string `identity:"tenant" json:"-"`
	query.Paginator
	query.Sorter
	Filters query.Filters `json:"-"`
}

ListTenantRegistrations pages the registration history of the namespace's tenant-only key.

type MemberList added in v0.27.0

type MemberList struct {
	TenantID string `param:"tenant" json:"-" 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 NamespaceAddMember added in v0.16.0

type NamespaceAddMember struct {
	UserID      string          `identity:"id" json:"-" validate:"required"`
	TenantID    string          `param:"tenant" json:"-" 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.

type NamespaceCreate

type NamespaceCreate struct {
	UserID string `identity:"id" json:"-" validate:"required"`
	Name   string `json:"name"  validate:"required,hostname_rfc1123,excludes=."`
	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"`
		RequireVerifiedDeviceKey *bool   `json:"require_verified_device_key" validate:"omitempty"`
	} `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 `identity:"id" json:"-"`
	TenantID string `identity:"tenant" json:"-"`
	IsAdmin  bool   `identity:"admin" json:"-"`
	query.Paginator
	query.Filters
}

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

type NamespaceMembershipInvitationList added in v0.27.0

type NamespaceMembershipInvitationList struct {
	TenantID string `param:"tenant" json:"-" validate:"required"`
	UserID   string `identity:"id" json:"-" 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 `identity:"id" json:"-" validate:"required"`
	TenantID string `param:"tenant" json:"-" validate:"required,uuid"`
	MemberID string `param:"uid" json:"-" validate:"required"`
	// KeepDevices names devices the member owns that stay as team devices instead of leaving.
	KeepDevices []string `query:"keep_devices" json:"-" validate:"omitempty,max=100,dive,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          `identity:"id" json:"-" validate:"required"`
	TenantID   string          `param:"tenant" json:"-" validate:"required,uuid"`
	MemberID   string          `param:"uid" json:"-" validate:"required"`
	MemberRole authorizer.Role `json:"role" validate:"omitempty,member_role"`
	// KeepDevices names devices the member owns that stay as team devices when the new role
	// cannot accept devices.
	KeepDevices []string `json:"keep_devices" validate:"omitempty,max=100,dive,required"`
}

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 added in v0.27.0

type OptionalInt struct {
	Present bool `json:"-"`
	Value   *int `json:"-"`
}

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 added in v0.27.0

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 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 `identity:"tenant" json:"-" validate:"required,uuid"`
	Name     string `param:"name" json:"-" 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 `json:"-" 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 `identity:"tenant" json:"-" validate:"required,uuid"`
	Name     string `param:"name" json:"-" 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 `json:"-" validate:"required"`
}

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

type RecordOnboardingSurvey added in v0.29.0

type RecordOnboardingSurvey struct {
	UserID  string                      `identity:"id" json:"-" validate:"required"`
	Outcome models.UserOnboardingSurvey `json:"outcome" validate:"required,oneof=answered skipped"`
}

RecordOnboardingSurvey is the request of the endpoint that records what the caller did with the onboarding survey.

type RegisterUser added in v0.27.0

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. It identifies the invitation and
	// joins its namespace, but it does not prove control of the email: the inviter holds the same
	// link. It's a human-readable pairing code, not a UUID.
	Sig string `json:"sig" validate:"omitempty"`

	// DeviceCode is the pairing code of a device waiting to be accepted, when the registration
	// started from an accept-device link. Cloud carries it into the confirmation email's link.
	DeviceCode string `json:"device_code" validate:"omitempty,device_pairing_code"`
}

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 RenewUserToken added in v0.30.0

type RenewUserToken struct {
	UserID   string `identity:"id" json:"-" validate:"required"`
	TenantID string `param:"tenant" json:"-" validate:"omitempty,uuid"`
	// TokenVersion is the version of the bearer being renewed, which the new token carries in
	// place of the user's current one. Nil mints at the user's current version. The handler
	// fills it from the authentication step; no client input reaches it.
	TokenVersion *int `json:"-"`
	// Impersonated mints a token an instance administrator acts as the user with. The admin
	// surface sets it, and every handler that mints a replacement for such a token keeps it; no
	// client input reaches it.
	Impersonated bool `json:"-"`
}

RenewUserToken is the request to replace a signed-in user's bearer, optionally scoped to one namespace. With no TenantID the token carries no namespace, which is what a user with no memberships gets.

type ResolveDevice added in v0.19.1

type ResolveDevice struct {
	TenantID string `identity:"tenant" json:"-" validate:"required"`
	UID      string `query:"uid" json:"-" validate:"required_without=Hostname"`
	Hostname string `query:"hostname" json:"-" validate:"required_without=UID"`
}

ResolveDevice is the request to find a device by UID or by hostname. One of the two is required, and UID wins when both are given.

type ResolveInvitation added in v0.27.0

type ResolveInvitation struct {
	Invite string `query:"invite" json:"-" 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 RevealProvisioningKey added in v0.27.0

type RevealProvisioningKey struct {
	TenantID string `identity:"tenant" json:"-"`
	Name     string `param:"name" json:"-" validate:"required"`
}

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

type RevokeUserTokens added in v0.27.0

type RevokeUserTokens struct {
	UserID string `identity:"id" json:"-" validate:"required"`
}

RevokeUserTokens is the request of the endpoint that revokes every token the caller holds.

type SSHApprovalConfirm added in v0.27.0

type SSHApprovalConfirm struct {
	Code string `param:"code" json:"-" 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 added in v0.27.0

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 added in v0.27.0

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

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

type SSHApprovalReject added in v0.27.0

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

SSHApprovalReject is the request data for the deny endpoint.

type SSHApprovalStatus added in v0.27.0

type SSHApprovalStatus struct {
	Code string `param:"code" json:"-" validate:"required"`
}

SSHApprovalStatus asks for the decision on one parked login. The gateway reads it once, after the client answers its approval prompt, and the code is normalized and checked in the service rather than here.

type SSHIdentityCreate added in v0.27.0

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 added in v0.27.0

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 added in v0.27.0

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

SSHIdentityIDParam represents an SSH identity id as a path param.

type SSHIdentityList added in v0.27.0

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 added in v0.27.0

type SSHIdentityUpdate struct {
	SSHIdentityIDParam
	TenantID string `json:"-"`
	UserID   string `json:"-"`
	Name     string `json:"name" validate:"required"`
	// Manage reports whether the caller holds the SSHIdentityManage permission,
	// allowing them to rename an identity that is not their own.
	Manage bool `json:"-"`
}

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

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"`
	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:""`
	// APIKeyID is the API key the session acts as, when an automation opened it. It is
	// separate from UserID because the two name different tables.
	APIKeyID string `json:"api_key_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 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" json:"-" validate:"required"`
}

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

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 {
	TenantID          string `query:"tenant_id" json:"-" validate:"omitempty,uuid"`
	PreferredHostname string `query:"preferred_hostname" json:"-" validate:"omitempty,device_name"`
	PreferredIdentity string `query:"preferred_identity" json:"-" validate:"omitempty,device_identity"`
}

SystemInstallScript is the request behind the install script an operator pipes into a shell. 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 TenantParam

type TenantParam struct {
	Tenant string `param:"tenant" json:"-" 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 `identity:"id" json:"-"`
	TenantID string `identity:"tenant" json:"-"`
	// 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" json:"-" 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 UpdateProvisioningKey added in v0.27.0

type UpdateProvisioningKey struct {
	UserID   string `identity:"id" json:"-"`
	TenantID string `identity:"tenant" json:"-"`
	// CurrentName is the current stored name (path param). It differs from [UpdateProvisioningKey.Name],
	// which is the optional new target name.
	CurrentName string `param:"name" json:"-" 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"`
}

UpdateProvisioningKey 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 `identity:"tenant" json:"-" validate:"required,uuid"`
	Name     string `param:"name" json:"-" 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 `identity:"id" json:"-" 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 UpgradeNamespace added in v0.27.0

type UpgradeNamespace struct {
	TenantParam
}

UpgradeNamespace is the request to upgrade a legacy namespace to a new one. It names the namespace by the tenant in the path and carries no body, since the upgrade has no options.

type UserMembershipInvitationList added in v0.27.0

type UserMembershipInvitationList struct {
	UserID string `identity:"id" json:"-"`
	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 `identity:"id" json:"-" 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 added in v0.27.0

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 caller's authenticated identity, never the body. Community validates Password; the enterprise overlay validates Code (TOTP) when the user has MFA.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL