apikeyep

type APIKeySvc interface {
	GetAPIKey(ctx context.Context, req *RetrieveAPIKeyRequest) (*apiresource.APIKey, *apierror.APIError)
	CreateAPIKey(ctx context.Context, req *CreateAPIKeyRequest) (*apiresource.CreatedAPIKey, *apierror.APIError)
	RotateAPIKey(ctx context.Context, req *RotateAPIKeyRequest) (*apiresource.CreatedAPIKey, *apierror.APIError)
	RevokeAPIKey(ctx context.Context, req *RevokeAPIKeyRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ListAPIKeys(ctx context.Context, req *ListAPIKeysRequest) (*apiresource.List[apiresource.APIKey], *apierror.APIError)
	GetOrCreateDocAPIKey(ctx context.Context) (*apiresource.CreatedAPIKey, *apierror.APIError)
}

type APIKeySvcConfig struct {
	// AuthClient (required) is the auth-service gRPC client.
	AuthClient pb.AuthServiceClient
}

type CreateAPIKeyEndpoint struct{}

type CreateAPIKeyRequest struct {
	// ID of the role to assign to the API key.
	//
	// The role determines what requests authenticated with the key are allowed to do. A key keeps its role for life — including through rotation — so issue a new key to use a different one, while changes to the role's own permissions take effect for existing keys immediately.
	RoleID string `json:"role_id" validate:"required"`
	// Human-readable name for the API key.
	//
	// Shown when listing keys and used to match keys when searching, so prefer something that identifies the integration using it.
	Name string `json:"name" validate:"required,max=255"`
	// When the key expires and stops authenticating requests.
	//
	// If omitted, the key keeps working until it is revoked or rotated.
	ExpiresAt field.Optional[time.Time] `json:"expires_at,omitzero"`
}

type GetDocAPIKeyEndpoint struct{}

type ListAPIKeysEndpoint struct{}

type ListAPIKeysRequest struct {
	apiresource.PaginationRequest
	// API key statuses to filter by.
	//
	// - `active`: the key still authenticates requests. A key whose revocation is scheduled for a future time is still active until that time arrives.
	// - `expired`: the key passed its expiration time without having been revoked.
	// - `revoked`: the key was revoked, which takes precedence over expiration.
	//
	// When omitted, keys of every status are returned.
	Statuses []constants.APIKeyStatus `query:"statuses" default:"active,expired,revoked"`
}

type RetrieveAPIKeyEndpoint struct{}

type RetrieveAPIKeyRequest struct {
	// API key ID.
	APIKeyID string `path:"id" validate:"required"`
}

type RevokeAPIKeyEndpoint struct{}

type RevokeAPIKeyRequest struct {
	// API key ID.
	APIKeyID string `path:"id" validate:"required"`
}

type RotateAPIKeyEndpoint struct{}

type RotateAPIKeyRequest struct {
	// ID of the API key to rotate.
	//
	// The key must not already be revoked.
	APIKeyID string `path:"id" validate:"required"`
	// When the replacement key should expire.
	//
	// If omitted, the replacement inherits the expiration of the key being rotated.
	ExpiresAt field.Optional[time.Time] `json:"expires_at,omitzero"`
	// When the old key should stop authenticating requests.
	//
	// If omitted, the old key is revoked immediately. Set a future timestamp — up to 30 days out — to keep the old key working during a migration window; a timestamp in the past revokes it immediately.
	RevokeAt field.Optional[time.Time] `json:"revoke_at,omitzero" validate:"omitempty,max_days_ahead=30"`
}