Slack Connect API

Table of Contents

• upsquad/slackconnect/v1/slackconnect.proto

  • ApplyRequest

  • ApplyResponse

  • ApplyUser

  • ApplyUsergroupMapping

  • CallbackRequest

  • CallbackResponse

  • ConnectRequest

  • ConnectResponse

  • DisconnectIntegrationRequest

  • DisconnectIntegrationResponse

  • GetIntegrationRequest

  • GetIntegrationResponse

  • Integration

  • PreviewUsergroupsRequest

  • PreviewUsergroupsResponse

  • PreviewUsersRequest

  • PreviewUsersResponse

  • SlackUserPreview

  • SlackUsergroupPreview

  • SlackConnectService

• Scalar Value Types

Top

upsquad/slackconnect/v1/slackconnect.proto

ApplyRequest

Field	Type	Label	Description
request_id	string		request_id is a client-supplied UUID used for idempotent retries. A second Apply with the same request_id short-circuits to the first call's result without re-running any writes.
users	ApplyUser	repeated	users is the subset of Slack users the admin selected for import.
usergroup_mappings	ApplyUsergroupMapping	repeated	usergroup_mappings pins a Slack usergroup to an UpsQuad org_unit. The members of the usergroup are added as memberships of the unit.

ApplyResponse

Field	Type	Label	Description
members_created	int32		members_created is the count of new UpsQuad members inserted by this call; members_linked is the count of Slack users that matched an existing email.
members_linked	int32
memberships_added	int32		memberships_added is the count of (member, org_unit) pairs newly inserted into org_unit_memberships.
warnings	string	repeated	warnings carries non-fatal issues (unmatched emails, skipped bots, …) so the console can surface them without failing the whole apply.

ApplyUser

Field	Type	Label	Description
slack_user_id	string
email	string
display_name	string
clearance	int32		clearance is the numeric tier assigned to newly-created members. Must be in [1..5]; existing members are NOT re-evaluated.

ApplyUsergroupMapping

Field	Type	Label	Description
slack_usergroup_id	string
org_unit_id	string		org_unit_id is the UpsQuad org_unit the Slack usergroup maps onto.
membership_role	string		membership_role is "member"

CallbackRequest

CallbackRequest carries the ?code and ?state returned by Slack.

Field	Type	Label	Description
code	string
state	string

CallbackResponse

CallbackResponse indicates success and returns the persisted integration summary.

Field	Type	Label	Description
integration	Integration

ConnectRequest

ConnectRequest initiates the OAuth handshake.

Field	Type	Label	Description
redirect_uri	string		redirect_uri is the console URL Slack should hand the code/state back to. MUST match one of the app's configured redirect URIs — Slack validates this server-side.

ConnectResponse

ConnectResponse returns the Slack authorize URL.

Field	Type	Label	Description
authorize_url	string		authorize_url is the full https://slack.com/oauth/v2/authorize?… URL.
state	string		state is the single-use nonce (UUID) baked into the authorize URL. Callers do not need to echo it manually — Slack includes it in the redirect — but it is returned here so the console can cross-check.

DisconnectIntegrationRequest

DisconnectIntegrationResponse

Field	Type	Label	Description
disconnected	bool

GetIntegrationRequest

GetIntegrationResponse

Field	Type	Label	Description
integration	Integration

Integration

Integration is the wire form of a slack_integrations row. The bot token is NEVER returned; this message carries only the identity + status fields the console needs.

Field	Type	Label	Description
id	string
org_id	string
slack_team_id	string
slack_team_name	string
slack_app_id	string
slack_bot_user_id	string
scopes	string	repeated
status	string		active
last_sync_at	google.protobuf.Timestamp
last_sync_status	string
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

PreviewUsergroupsRequest

PreviewUsergroupsResponse

Field	Type	Label	Description
usergroups	SlackUsergroupPreview	repeated

PreviewUsersRequest

Field	Type	Label	Description
cursor	string		cursor is the Slack pagination cursor from the previous page; empty on the first call.
page_size	int32		page_size clamps to [1, 200]. Defaults to 100 when 0.

PreviewUsersResponse

Field	Type	Label	Description
users	SlackUserPreview	repeated
next_cursor	string		next_cursor is empty when there are no more pages.

SlackUserPreview

SlackUserPreview is one row of the preview grid.

Field	Type	Label	Description
slack_user_id	string
slack_team_id	string
display_name	string
real_name	string
email	string
is_bot	bool
is_deleted	bool
match_kind	string		match_kind describes whether this Slack user already has a matching UpsQuad member (by email). Values: new
existing_member_id	string		existing_member_id is populated when match_kind is match

SlackUsergroupPreview

Field	Type	Label	Description
slack_usergroup_id	string
handle	string		e.g. "engineering"
name	string		human-readable
description	string
slack_user_ids	string	repeated	members

SlackConnectService

SlackConnectService drives the OAuth v2 flow + preview/apply for the single-app Slack integration.

--- OAuth flow ---

Method Name	Request Type	Response Type	Description
Connect	ConnectRequest	ConnectResponse	Connect mints a single-use oauth state row and returns the Slack authorize URL the console should redirect the admin to. The returned state MUST be echoed back to Callback — replays are rejected.
Callback	CallbackRequest	CallbackResponse	Callback exchanges an OAuth v2 authorization code for a bot token and persists the integration. Idempotent on (org_id, slack_team_id): a re-install for the same Slack workspace rotates the stored token.
GetIntegration	GetIntegrationRequest	GetIntegrationResponse	GetIntegration returns the current integration row for the tenant (never the raw token). Returns NOT_FOUND when no active row exists.
DisconnectIntegration	DisconnectIntegrationRequest	DisconnectIntegrationResponse	DisconnectIntegration soft-deletes the current integration and zeroes the vault entry. Idempotent.
PreviewUsers	PreviewUsersRequest	PreviewUsersResponse	PreviewUsers pages through Slack users.list and returns a diff-view the console can render: whether each Slack user already has a matching UpsQuad member (by email), along with the fields we'd create/update.
PreviewUsergroups	PreviewUsergroupsRequest	PreviewUsergroupsResponse	PreviewUsergroups returns usergroups.list (including members) so the console can render a mapping UI for org_units.
Apply	ApplyRequest	ApplyResponse	Apply takes the admin's selection of users + usergroup→org_unit mappings and creates members / memberships inside a single transaction. Members are upserted by email: existing members are linked, new members are inserted. Idempotent against the same request_id (UUID supplied by the client) — replays return the original result without side-effects.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)