Nucleus SDK for Go

The official Nucleus Go SDK provides discovery-first access for fixed-tenant machine integrations and a separate signed client for app-entitlement services. It keeps permissions, tenancy, validation, and business rules on the server.

Requirements

• Go 1.26 or newer
• A Nucleus SDK version matching the Nucleus server release
• An HTTPS Nucleus endpoint, except for loopback development
• A fixed-tenant API key with only the required scopes

App-entitlement service integrations use a tenant- and app-bound service credential instead of an API key. Never pass that credential to NewClient.

Install

Nucleus SDK versions follow the Nucleus release. For Nucleus 8:

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

The module path changes to /v8, /v9, and so on when the Nucleus major version changes.

Quickstart

credential := nucleus.APIKeyCredential{
    ID: os.Getenv("NUCLEUS_API_KEY_ID"),
    Secret: os.Getenv("NUCLEUS_API_KEY_SECRET"),
}
client, err := nucleus.NewClient("https://nucleus.example.com", credential)
if err != nil {
    log.Fatal(err)
}

authenticatedContext, err := client.CurrentContext(context.Background())
if err != nil {
    log.Fatal(err)
}
fmt.Println("tenant:", authenticatedContext.TenantID)

entrypoints, err := client.ResourceEntrypoints(context.Background())
if err != nil {
    log.Fatal(err)
}
fmt.Println("visible resources:", len(entrypoints))

Write operations remain opt-in and are never retried automatically. Use only structured actions advertised by the server. For example, a receiving command passes the required idempotency header through ExecuteAction:

func executeIdempotentAction(
    ctx context.Context,
    client *nucleus.Client,
    action nucleus.EntrypointAction,
    command any,
    operationID string,
) (nucleus.ActionResult, error) {
    return client.ExecuteAction(ctx, action, command, map[string]string{
        "Idempotency-Key": operationID,
    })
}

Never log API keys, Authorization headers, request payloads, or complete error response bodies.

For an app-entitlement service, construct the separate client with the complete one-time credential returned by Nucleus:

credential, err := nucleus.NewEntitlementsServiceCredential(
    os.Getenv("NUCLEUS_APP_SERVICE_CREDENTIAL"),
)
if err != nil {
    log.Fatal(err)
}
client, err := nucleus.NewEntitlementsServiceClient(
    "https://nucleus.example.com",
    credential,
)
if err != nil {
    log.Fatal(err)
}

projection, err := client.Introspect(context.Background(), actorID)
if err != nil {
    log.Fatal(err)
}
fmt.Println("entitlement state:", projection.State)

The service client signs each request with a fresh nonce and never retries grant issuance. See App entitlement service for snapshot, change-feed, grant, and JWKS usage.

The runnable examples/quickstart validates API v1, selects a readable server-advertised resource, and requests at most one item. Provide NUCLEUS_URL, NUCLEUS_API_KEY_ID, and NUCLEUS_API_KEY_SECRET; optionally set NUCLEUS_DEMO_RESOURCE_ID to require a specific advertised resource.

go run ./examples/quickstart

Documentation

• Getting started
• Authentication
• Resources
• App entitlement service
• Errors and diagnostics
• Compatibility and releases
• Contributing

SDK prose and public identifiers are English. Documentation lives below docs/en so future translations can be added without changing APIs. The SDK does not localize runtime text; applications map stable errorCode values to their own messages.

License

Apache License 2.0. See LICENSE.