> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# external_sync
> sift/external_sync/v1/external_sync.proto
## Services
*RPC methods exposed by this API.*
### ExternalSyncService
| Method | Request | Response | Description |
| :---------------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SyncOrganization | [SyncOrganizationRequest](#syncorganizationrequest) | [SyncOrganizationResponse](#syncorganizationresponse) | |
| GenerateToken | [GenerateTokenRequest](#generatetokenrequest) | [GenerateTokenResponse](#generatetokenresponse) | |
| GetExternalSync | [GetExternalSyncRequest](#getexternalsyncrequest) | [GetExternalSyncResponse](#getexternalsyncresponse) | |
| ListExternalSyncTokens | [ListExternalSyncTokensRequest](#listexternalsynctokensrequest) | [ListExternalSyncTokensResponse](#listexternalsynctokensresponse) | |
| ListExternalSyncRuns | [ListExternalSyncRunsRequest](#listexternalsyncrunsrequest) | [ListExternalSyncRunsResponse](#listexternalsyncrunsresponse) | |
| GetExternalSyncRun | [GetExternalSyncRunRequest](#getexternalsyncrunrequest) | [GetExternalSyncRunResponse](#getexternalsyncrunresponse) | |
| GetIsOrgExternallyProvisioned | [GetIsOrgExternallyProvisionedRequest](#getisorgexternallyprovisionedrequest) | [GetIsOrgExternallyProvisionedResponse](#getisorgexternallyprovisionedresponse) | Organization admins (Admin role in the org) and platform admins may call. Returns whether the org has IdP/SCIM external sync configured (users should be provisioned via the identity provider). Organization is taken from request context. |
## Messages
*Data models used across requests/responses.*
### ExternalSync
| Field | Type | Label | Description |
| :-------------------------------- | :------------------------ | :------- | :---------- |
| organization\_id | string | | |
| most\_recent\_sync\_date | google.protobuf.Timestamp | optional | |
| most\_recent\_sync\_by\_user\_id | string | optional | |
| scim\_server\_url | string | | |
| token\_created\_date | google.protobuf.Timestamp | optional | |
| token\_lifetime\_seconds | uint32 | | |
| most\_recent\_token\_by\_user\_id | string | optional | |
### ExternalSyncGroupRef
Sift user group identity for display (group\_name) and stable API use (user\_group\_id).
| Field | Type | Label | Description |
| :-------------- | :----- | :---- | :---------- |
| user\_group\_id | string | | |
| group\_name | string | | |
### ExternalSyncMembershipChange
One membership edge that changed during the sync.
| Field | Type | Label | Description |
| :-------------- | :----- | :---- | :---------- |
| user\_id | string | | |
| user\_name | string | | |
| user\_group\_id | string | | |
| group\_name | string | | |
### ExternalSyncRun
| Field | Type | Label | Description |
| :---------------------- | :-------------------------------------------------------- | :------- | :---------- |
| external\_sync\_run\_id | string | | |
| synced\_at | google.protobuf.Timestamp | | |
| trigger\_type | [ExternalSyncRunTriggerType](#externalsyncruntriggertype) | | |
| triggered\_by\_user\_id | string | optional | |
| diff | [ExternalSyncRunDiff](#externalsyncrundiff) | | |
### ExternalSyncRunDiff
Snapshot of membership and lifecycle changes from one external sync run.
Identifiers are Sift `user_id` / `user_group_id` UUIDs and human-readable names as stored in Sift
(not Keycloak SCIM ids). Older stored runs may have empty ids with names only.
| Field | Type | Label | Description |
| :--------------------------- | :------------------------------------------------------------ | :------- | :---------- |
| users\_activated | [ExternalSyncUserRef](#externalsyncuserref) | repeated | |
| users\_deactivated | [ExternalSyncUserRef](#externalsyncuserref) | repeated | |
| groups\_created | [ExternalSyncGroupRef](#externalsyncgroupref) | repeated | |
| groups\_deleted | [ExternalSyncGroupRef](#externalsyncgroupref) | repeated | |
| users\_added\_to\_groups | [ExternalSyncMembershipChange](#externalsyncmembershipchange) | repeated | |
| users\_removed\_from\_groups | [ExternalSyncMembershipChange](#externalsyncmembershipchange) | repeated | |
### ExternalSyncRunSummary
| Field | Type | Label | Description |
| :---------------------------------- | :-------------------------------------------------------- | :------- | :---------- |
| external\_sync\_run\_id | string | | |
| synced\_at | google.protobuf.Timestamp | | |
| trigger\_type | [ExternalSyncRunTriggerType](#externalsyncruntriggertype) | | |
| triggered\_by\_user\_id | string | optional | |
| users\_activated\_count | uint32 | | |
| users\_deactivated\_count | uint32 | | |
| groups\_created\_count | uint32 | | |
| groups\_deleted\_count | uint32 | | |
| users\_added\_to\_groups\_count | uint32 | | |
| users\_removed\_from\_groups\_count | uint32 | | |
### ExternalSyncToken
The actual token value is not returned after it is first generated.
| Field | Type | Label | Description |
| :-------------------- | :------------------------ | :---- | :---------- |
| token\_id | string | | |
| lifetime\_seconds | uint32 | | |
| created\_date | google.protobuf.Timestamp | | |
| created\_by\_user\_id | string | | |
### ExternalSyncUserRef
Sift user identity for display (user\_name) and stable API use (user\_id).
| Field | Type | Label | Description |
| :--------- | :----- | :---- | :---------- |
| user\_id | string | | |
| user\_name | string | | |
### GenerateTokenRequest
*This message has no fields.*
### GenerateTokenResponse
| Field | Type | Label | Description |
| :------------- | :---------------------------- | :---- | :---------- |
| external\_sync | [ExternalSync](#externalsync) | | |
| token | string | | |
### GetExternalSyncRequest
*This message has no fields.*
### GetExternalSyncResponse
| Field | Type | Label | Description |
| :------------- | :---------------------------- | :---- | :---------- |
| success | bool | | |
| external\_sync | [ExternalSync](#externalsync) | | |
### GetExternalSyncRunRequest
| Field | Type | Label | Description |
| :---------------------- | :----- | :---- | :---------- |
| external\_sync\_run\_id | string | | |
### GetExternalSyncRunResponse
| Field | Type | Label | Description |
| :------------------ | :---------------------------------- | :---- | :---------- |
| external\_sync\_run | [ExternalSyncRun](#externalsyncrun) | | |
### GetIsOrgExternallyProvisionedRequest
*This message has no fields.*
### GetIsOrgExternallyProvisionedResponse
| Field | Type | Label | Description |
| :-------------------------- | :--- | :---- | :---------- |
| is\_externally\_provisioned | bool | | |
### ListExternalSyncRunsRequest
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :---------- |
| page\_size | uint32 | | |
| page\_token | string | | |
| filter | string | | |
| order\_by | string | | |
### ListExternalSyncRunsResponse
| Field | Type | Label | Description |
| :----------------------------- | :------------------------------------------------ | :------- | :---------- |
| external\_sync\_run\_summaries | [ExternalSyncRunSummary](#externalsyncrunsummary) | repeated | |
| next\_page\_token | string | | |
### ListExternalSyncTokensRequest
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | The maximum number of tokens to return. The service may return fewer than this value. If unspecified, at most 50 tokens will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListExternalSyncTokens` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListExternalSyncTokens` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. There are currently no available fields. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). |
| order\_by | string | | How to order the retrieved user defined functions. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available field to order\_by is `created_date`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date asc". |
### ListExternalSyncTokensResponse
| Field | Type | Label | Description |
| :--------------------- | :-------------------------------------- | :------- | :---------- |
| external\_sync\_tokens | [ExternalSyncToken](#externalsynctoken) | repeated | |
| next\_page\_token | string | | |
### SyncOrganizationRequest
*This message has no fields.*
### SyncOrganizationResponse
| Field | Type | Label | Description |
| :--------------------------------- | :--------------------------------------------------------------- | :------- | :---------- |
| external\_sync | [ExternalSync](#externalsync) | | |
| existing\_user\_count | uint32 | | |
| added\_to\_organization\_user\_ids | string | repeated | |
| created\_users | [sift.common.type.v1.User](#sift-common-type-v1-user) | repeated | |
| deactivated\_user\_ids | string | repeated | |
| existing\_group\_count | uint32 | | |
| created\_user\_groups | [sift.user\_groups.v2.UserGroup](#sift-user_groups-v2-usergroup) | repeated | |
| deleted\_user\_group\_names | string | repeated | |
## Enums
*Allowed constant values used in message fields.*
### ExternalSyncRunTriggerType
| Name | Number | Description |
| :----------------------------------------------- | :----- | :------------------------------------------ |
| EXTERNAL\_SYNC\_RUN\_TRIGGER\_TYPE\_UNSPECIFIED | 0 | |
| EXTERNAL\_SYNC\_RUN\_TRIGGER\_TYPE\_MANUAL\_USER | 1 | User triggered sync via the Sift UI or API. |
| EXTERNAL\_SYNC\_RUN\_TRIGGER\_TYPE\_SCHEDULED | 2 | |