Connect Sage X3: verify Sync API connectivity for your folder

Collect the seven values issued at tenant onboarding — environment, Sync API base URL, folder, tenant API key and the Sage identity OAuth pair — fill them into Integration and test: the test exchanges a token and probes your folder. This connection verifies connectivity only and does not sync orders, inventory or customers.

The Sage X3 connection verifies that this system can reach the Sync API of one Sage X3 folder on your tenant: it exchanges a Sage identity token and reads the change feed of that folder once. Keep the scope in mind — verifying connectivity is all this connection does today. It does not pull orders, customers or inventory in, and it does not push inventory back, because the Sync API is a general table-level sync interface and the table names and column mapping for orders, inventory and customers have to be confirmed against your own folder metadata for your deployment. A passed test proves the seven values below work together for that folder, and nothing more.

Prerequisites#

• A Sage X3 deployment whose tenant has the Sync API available, and one X3 folder you want to verify, for example SEED.
• The tenant onboarding pack for that deployment: the Sync API base URL, the tenant API key, and the exact folder name. Folder names are case-sensitive, so keep the exact spelling you were given.
• A Sage identity OAuth client credentials pair (a client ID and a client secret) issued for this tenant, from the same onboarding.
• You know which environment you are connecting: production or test. The word you fill in decides which Sage token address the test uses.

Get your credentials#

1. Ask your Sage X3 administrator, or the team that ran your tenant onboarding, for the onboarding pack of this deployment. All seven values of this connection come from that onboarding — there is no separate sign-up page in this guide, and no value should be invented or borrowed from another tenant.
2. From the pack, note the Sync API base URL of your tenant, in the form https://tenant-host/syncapi, with your own tenant host in it.
3. Note the folder name exactly as written in the pack, letter case included — for example SEED. The test later asks for that folder by this exact name.
4. Note the tenant API key from the pack and keep it secret. During the test it is sent as the X-API-KEY header, together with the token.
5. Note the Sage identity OAuth client ID and client secret from the same pack. The two belong together as one pair — do not mix the secret of one pair with the ID of another.
6. Check whether the pack asks for a token audience. Only if your onboarding documents require one do you need that value — otherwise leave it for the fill-in step to stay empty.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Sage X3 → New connection.
2. environment — required, Environment: type the literal word production for your live tenant, or test for your test tenant. production uses the Sage token address https://id.sage.com/oauth/token, and test uses https://id-shadow.sage.com/oauth/token.
3. tenant_base_url — required, Tenant Sync API base URL: paste the Sync API base URL issued at onboarding, for example https://tenant-host/syncapi, with your own tenant host.
4. folder — required, X3 folder: type the folder name exactly as issued, for example SEED. This field is case-sensitive — seed and SEED are different names here.
5. tenant_api_key — required, Tenant API key: paste the tenant API key from the onboarding pack. It is a password-type field, stored as a secret, and sent as the X-API-KEY header during the test.
6. client_id — required, OAuth client ID: paste the client ID of the Sage identity OAuth pair from the same pack. It is a password-type field and stored as a secret.
7. client_secret — required, OAuth client secret: paste the client secret of that same OAuth pair. It is a password-type field and stored as a secret. The ID and the secret must come from the same pair.
8. audience — optional, Token audience: fill this only when your tenant onboarding documents explicitly ask for a token audience. Otherwise leave it empty — the test then asks for the token without an audience.

Test the connection#

Click Test connection. The test first checks the five required credential values and stops with a named result if one is missing: MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID or MISSING_CLIENT_SECRET. It then runs two real steps inside one shared 12-second limit. First, it exchanges your client_id and client_secret for a Sage identity token at the address your environment selects, adding audience when you filled one in. Second, it asks your tenant Sync API for the changes of your folder, sending both the token as Authorization: Bearer and your tenant API key as X-API-KEY. An answer of 200 passes, and the result names the folder it reached. A 401 is reported as INVALID_TOKEN, a 403 as MISSING_SCOPE, and a 404 as NOT_FOUND — see the FAQ for what each one means.

Mapping / pick a template#

There is no standard mapping and no template to pick for this connection. The Sync API works at table level, and the table names and columns for orders, inventory and customers differ per folder, so they are confirmed against your folder metadata when a data connection is set up for your deployment — they are not something to guess or to fill in here. Until that per-deployment confirmation exists for your folder, this connection stays at the connectivity check it performs in the test step. Do not rename tables or fields in Sage X3 to match a guessed mapping.

Activate#

After the test passes, activate the connection to save it in Integration with these verified values, so the same folder can be checked again later with the same credentials. Activation does not start any data flow: no orders, customers or inventory move through this connection, in either direction. If your onboarding later issues a new tenant API key or a new OAuth pair, update the fields here and test again before relying on the connection.

FAQ#

Test fails with INVALID_TOKEN (401)

The token side of the check was refused. Either the token exchange itself rejected your client_id and client_secret pair, or the token that came back was not accepted by the tenant Sync API. The usual causes are a copied value with extra spaces, the secret of one OAuth pair used with the ID of another, or an environment word that sends the exchange to the other Sage token address than the pair was issued for.

Re-copy client_id and client_secret from the same onboarding pack, with no extra spaces, and confirm environment matches the tenant that pair was issued for — production for the live tenant, test for the test tenant. If you filled in audience, remove it unless your onboarding documents require one, then test again.

Test fails with MISSING_SCOPE (403)

The token was accepted, but your tenant API key has no permission for the folder named in the folder field. The request reached the Sync API of your tenant — the key itself is the limit, not the address and not the OAuth pair.

Ask your Sage X3 administrator to grant that tenant API key access to this folder, or to issue a key that covers it. Confirm the folder name while you are there, then test again with the updated key.

Test fails with NOT_FOUND (404)

The folder named in the folder field is not enabled for the Sync API on this tenant, or the name does not match a folder there. Because folder names are case-sensitive, even the right name in the wrong letter case reads as a different folder.

Compare the folder value character by character with the onboarding pack, including capital letters. If the spelling is exact, ask your Sage X3 administrator to enable that folder for the Sync API, then test again.

Test stops with MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID or MISSING_CLIENT_SECRET

The result names the exact field that is empty. The test checks the fields first and sends nothing until all five are present, because the folder probe needs the token and the API key together.

Fill in the named field from your onboarding pack — base URL, folder, tenant API key, OAuth client ID or OAuth client secret — save, and test again. Repeat until no missing result appears.

I typed a server address or a full URL into environment and the test fails

environment is not an address field. It takes only one of two literal words, and the word selects which Sage token address the test uses. Any other content sends the token exchange to the wrong place, or nowhere usable.

Replace the environment value with the single word production if this connection is for your live tenant, or test if it is for your test tenant. Put the server address in tenant_base_url instead, then test again.

The test passed, but no orders, inventory or customers are synced

That is the current scope of this connection, not a fault in your values. The test only proves that the token exchange and the folder probe work. Data movement is not part of this connection yet, because the Sync API is table-level and the order, inventory and customer tables and columns of your folder first have to be confirmed against your folder metadata for your deployment.

Treat a passed test as a verified connection for this folder, and keep order, inventory and customer work in Sage X3 itself for now. When a data connection is set up for your deployment, it will start from these same verified values — you will not need to collect the credentials again.