Unidirectional Sync over Federated Repositories

Overview

Unidirectional Sync adds a Transmission Mode per federation member:

bidirectional (default) — members send and receive.
receiver (new) — member is Get-Only within that repository's federation. Outbound federation processing and Full-Sync initiation are skipped for the receiver. Monitoring reflects Receiving Only semantics.

Primary benefits

Governance & Compliance: Keep satellite/third-party sites in a receive-only posture.
Operational Simplicity: Use federation's streaming, auto-healing, and observability; avoid job-scheduling overhead of replication.
Deterministic Hub-and-Spoke: Enforce Source → Target flows with clear ownership, which reduces the cost of storage and network traffic by preventing unnecessary artifact synchronization from the spoke (Target) back to the hub (Source).

Prerequisites

Artifactory Federation Service installed and connected on Source and Target JPDs.
Both JPDs should be on the supported versions.
Network reachability between JPDs for API + binaries.
Admin permissions on Source; minimal required on Target.
Tokens/Trust options:
- Option A (recommended): Service Trust Pairing → issue a receiving only master token for enforcement.
  Note
  This option is recommended when the customer needs to assure the target site is not capable of pushing content to the source due to governance or compliance reasons. Since the master token itself is receiving-only, it enforces restrictions across the entire site for the pairing, meaning:
  The Target JPD's admin cannot build federations that push content back to the Source.
  All federations built from Source to Target using this pairing will be receiving-only on the Target side.
- Option B: Regular master token with full permissions — works functionally but does not enforce receiving-only posture at the trust boundary.
  Note
  This option is typically used when the customer wants the flexibility to establish both bidirectional and unidirectional federations between the Source and Target JPDs. The unidirectional flow is usually selected on a per-repository basis (by setting the member mode to receiver) mainly to save on storage and network traffic. In this case, there is no site-level enforcement that the target members are receiving-only; enforcement relies entirely on the repository configuration.

Endpoints

Service Trust
- Method & Path: POST /artifactory/api/v1/service_trust/pairing/federated-repo/r
  Purpose: Source creates read pairing token
- Method & Path: PUT /artifactory/api/v1/service_trust/pairing/federated-repo/r
  Purpose: Target exchanges pairing token → receiving-only master token
- Method & Path: PUT /artifactory/api/v1/service_trust/pairing/federated-repo/*
  Purpose: Same as above when the pairing token was created with /r
Repo Config
- Method & Path: PUT /artifactory/api/repositories/{repoKey}
  Purpose: Create federated repo, set member mode: "receiver"
- Method & Path: POST /artifactory/api/repositories/{repoKey}
  Purpose: Update members/mode
Monitoring
- Method & Path: GET /artifactory/api/federation/status/connectionStates/{repoKey}
  Purpose: Per-repo connections (status, lag, queued events, support, disabled)
- Method & Path: GET /artifactory/api/federation/status/stateSummary
  Purpose: JPD-wide aggregated counts of federation connections by state (across all federated repos on this JPD)

Steps

Step 1 — Establish Receiving-Only Trust (Service Trust Pairing)

Skip to Step 2 if you choose Option B: regular master token.

1A. Generate a read-permission pairing token on the Source JPD

POST {{jpd_url}}/artifactory/api/v1/service_trust/pairing/federated-repo/r
Authorization: Bearer <admin_or_scoped_token>

Response (example):

{ "pairing_token": "<PAIRING_TOKEN>", "expires_in": 300 }

1B. Exchange the pairing token on the Target JPD to obtain a receiving-only master token

PUT {{jpd_url}}/artifactory/api/v1/service_trust/pairing/federated-repo/r
Authorization: Bearer <admin_or_scoped_token>
Content-Type: application/json

{ "pairing_token": "<PAIRING_TOKEN>" }

Alternative (equivalent when pairing token was created with /r):

PUT {{jpd_url}}/artifactory/api/v1/service_trust/pairing/federated-repo/*

Outcome: Target now holds a receiving-only master token suitable for creating Receiver-restricted membership with the Source.

Step 2 — Create (or Update) the Federated Repository on the Source

2A. Create a federated repository with the Target as Receiver

PUT {{jpd_url}}/artifactory/api/repositories/{{source_repo_name}}
Content-Type: application/json
Authorization: Bearer <admin_or_scoped_token>

{
  "rclass": "federated",
  "packageType": "generic",
  "members": [
    {
      "url": "{{memberUrl}}/artifactory/{{target_repo_name}}",
      "mode": "receiver"
    }
  ]
}

2B. Update an existing federated repository to set Receiver mode

POST {{jpd_url}}/artifactory/api/repositories/{{source_repo_name}}
Content-Type: application/json
Authorization: Bearer <admin_or_scoped_token>

{
  "members": [
    {
      "url": "{{memberUrl}}/artifactory/{{target_repo_name}}",
      "mode": "receiver"
    }
  ]
}

Step 3 — Initial Synchronization & Verify

3A. Automatic Full Sync on create/update

On repository create/update, Artifactory triggers a Full Sync automatically from the Source to the Target (receiver). No manual Full Sync call is required for initial synchronization. The reverse direction (Target → Source) is not possible in receiver mode.

3B. Validate health

GET {{jpd_url}}/artifactory/api/federation/status/connectionStates/{{source_repo_name}}
GET {{jpd_url}}/artifactory/api/federation/status/stateSummary

Receiver members surface as Receiving_Only; outbound processing and Full-Sync initiation are skipped for that member.

API Guide

Service Trust Pairing (Unidirectional Enforcement)

Generate pairing token (read):

POST /artifactory/api/v1/service_trust/pairing/federated-repo/r

Exchange pairing token:

PUT /artifactory/api/v1/service_trust/pairing/federated-repo/r

PUT /artifactory/api/v1/service_trust/pairing/federated-repo/*

(equivalent for r pairing tokens)

Repository Configuration

Create federated repo with Receiver member:

PUT /artifactory/api/repositories/{repoKey}

Update members/mode:

POST /artifactory/api/repositories/{repoKey}