Connect a machine integration with a Workspace SDK

Use the official Go SDK for a server-side integration bound to one tenant. After this quickstart, your service discovers the resources it may use and accesses them with a restricted API key. Node.js and PHP packages are prepared but have not been published yet.

Choose an SDK

Use these SDKs in a backend or worker. Never bundle the Node.js client or its API key into browser code. Use the Android SDK for native Android apps.

Prerequisites

• a Workspace installation reachable over HTTPS,
• a tenant-bound API key with only the required permissions,
• the same version number for Workspace and the SDK.

The Go SDK is supported from Workspace 8.1.0. Node.js and PHP will be enabled only after their separate first-publication reviews. Until then, use the documented HTTP contract or nucli for those runtimes.

Install the package

Install the exact version of your Workspace installation:

go get git.schukai.me/releases/nucleus-sdk-go/v8@v8.1.0

The Go module path changes with each new Workspace major version, for example from /v7 to /v8.

Connect the client

Pass the base URL, key ID, and key secret through your application's secure runtime configuration. The client first calls public discovery and then loads authenticated resource entrypoints. Use only the returned same-origin URLs; do not construct resource paths yourself.

The Go client can also read the server-selected tenant and identity IDs with CurrentContext. Compare both values with the activated connector configuration before the first business request. The connector must not start if either value is missing or differs. This check complements server-side authorization; it does not replace it.

The SDKs cover discovery, resource entrypoints, resource metadata, lists, and server-provided actions. An entrypoint without a direct HTTP method can contain structured actions. Select an action by its stable ID and invoke it with ExecuteAction or executeAction. Supply exactly the advertised required headers. The SDK verifies the expected status and exposes only allowed response headers. Business payloads remain JSON. Interactive sign-in, 2FA, and session management are outside the machine profile.

For an idempotent write, pass the server-required key through ExecuteAction. The Go client sends only headers advertised by discovery and never retries writes automatically.

Connect a receiving integration

The receiving integration advertises three actions: read reference data, read expected purchase-order items, and apply an inspected final decision. Grant the API key receiving_integrations:read, receiving_integrations:receive, or both, depending on the connector's task. No bundled IAM preset grants these permissions automatically. Create a dedicated machine role for the connector and assign only the permissions it needs.

For a write, operationId must exactly match the Idempotency-Key header. Keep the value stable for the same logical operation. An identical replay returns the stored result; a changed payload with the same ID returns HTTP 409 and ERR_IDEMPOTENCY_CONFLICT. Accepted quantities may be booked into inventory. Fully rejected or quarantined quantities stay in the Receiving Case process and do not create a goods receipt. The server accepts at most 500 items and a request body up to 256 KiB.

Each package contains a runnable examples/quickstart program. It validates API v1, selects a readable entrypoint advertised by the server, and requests at most one item. Its README lists the required environment variables and the language-specific command.

Verify the result

Your setup is complete when:

1. discovery reports API major v1,
2. CurrentContext confirms the expected tenant and identity,
3. the resource call returns only entrypoints allowed for the key and tenant,
4. the client uses only server-advertised actions and headers,
5. your integration handles failures by HTTP status and stable errorCode.

Never log API keys, Authorization headers, complete payloads, or full error responses. Map errorCode to your own localized application message; the SDKs currently provide English technical text only.

Next step

Open the package's English README after installation. It provides language-specific examples for authentication, resources, error handling, and compatibility.