Go SDK

Full Go SDK reference with service namespaces

Go SDK

The Go SDK provides 103 methods across all PlatformXe services with zero external dependencies (stdlib net/http only). It includes retry with exponential backoff, configurable timeout, and circuit breaker support.

go get github.com/calderax/platformxe-go

package main

import px "github.com/calderax/platformxe-go"

func main() {
    client := px.NewClient(px.ClientConfig{
        APIKey: "pxk_live_your_key_here",
    })
    // Use client.Permissions, client.Messaging, etc.
}

Service namespaces

The client exposes 10 service namespaces with 103 methods total.

---

client.Permissions (36 methods)

Permission checks, role management, policies, relationships, federation, and audit.

Check & resolve

// Check a single permission
result, err := client.Permissions.Check("usr_123", "chat/session", "READ")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Allowed) // true or false

// Batch check multiple permissions
results, err := client.Permissions.BatchCheck("usr_123", []px.PermissionCheck{
    {Path: "chat/session", Action: "READ"},
    {Path: "chat/session", Action: "WRITE"},
})

// Resolve all permissions for a user
resolved, err := client.Permissions.Resolve("usr_123")

Roles

// List roles
roles, err := client.Permissions.ListRoles()

// Create a role
role, err := client.Permissions.CreateRole(px.CreateRoleInput{
    Name:        "Support Agent",
    Description: "Can view and manage support tickets",
    Model:       "SIMPLE",
})

// Get a role
role, err := client.Permissions.GetRole("role_abc123")

// Update a role
err = client.Permissions.UpdateRole("role_abc123", px.UpdateRoleInput{
    Name: "Senior Agent",
})

// Delete a role
err = client.Permissions.DeleteRole("role_abc123")

// Assign role to user
err = client.Permissions.AssignRole("usr_123", "role_abc123")

// Unassign role from user
err = client.Permissions.UnassignRole("usr_123", "role_abc123")

Capabilities (SIMPLE model)

// Set capabilities on a role
err = client.Permissions.SetCapabilities("role_abc123", []string{
    "chat:read", "chat:write", "tickets:read",
})

// Get capabilities for a role
caps, err := client.Permissions.GetCapabilities("role_abc123")

Module permissions (FULL model)

// Set module permissions
err = client.Permissions.SetModulePermissions("role_abc123", "mod_xyz", map[string]bool{
    "read": true, "write": true, "delete": false,
})

// Get module permissions
perms, err := client.Permissions.GetModulePermissions("role_abc123", "mod_xyz")

Resource policies (ABAC)

// Create a resource policy
policy, err := client.Permissions.CreateResourcePolicy(px.CreatePolicyInput{
    Name:         "EU Data Access",
    ResourcePath: "data/*",
    Conditions: px.Conditions{
        All: []px.Condition{
            {Attribute: "user.region", Operator: "eq", Value: "EU"},
        },
    },
})

// List resource policies
policies, err := client.Permissions.ListResourcePolicies()

// Update a resource policy
err = client.Permissions.UpdateResourcePolicy("pol_abc", px.UpdatePolicyInput{
    Name: "Updated Policy",
})

// Delete a resource policy
err = client.Permissions.DeleteResourcePolicy("pol_abc")

Relationships (ReBAC)

// Create a relationship
err = client.Permissions.CreateRelationship(px.CreateRelationshipInput{
    SubjectType: "user",
    SubjectID:   "usr_123",
    Relation:    "viewer",
    ObjectType:  "document",
    ObjectID:    "doc_456",
})

// List relationships
rels, err := client.Permissions.ListRelationships("user", "usr_123")

// Delete a relationship
err = client.Permissions.DeleteRelationship("rel_abc")

// Check relationship
result, err := client.Permissions.CheckRelationship(px.CheckRelationshipInput{
    SubjectType: "user",
    SubjectID:   "usr_123",
    Relation:    "viewer",
    ObjectType:  "document",
    ObjectID:    "doc_456",
})

Overrides

// Create an override
err = client.Permissions.CreateOverride(px.CreateOverrideInput{
    AdminID: "usr_123",
    Path:    "admin/settings",
    Action:  "WRITE",
    Effect:  "DENY",
})

// List overrides
overrides, err := client.Permissions.ListOverrides("usr_123")

// Delete an override
err = client.Permissions.DeleteOverride("ovr_abc")

Federation (permissions — v1.x.x admin permissions cross-app sync)

// Create federation group
group, err := client.Permissions.CreateFederationGroup(px.CreateFederationGroupInput{
    Name:        "Caldera Suite",
    Description: "Cross-app permission sharing",
})

// Add member to federation group
err = client.Permissions.AddFederationMember("fg_abc", "app_xyz")

// Sync federation permissions
err = client.Permissions.SyncFederation("fg_abc")

Note: This is the v1.x.x Permission Federation surface (Federation* types in types.go) — it shares admin permission modules + role grants across Caldera apps. For sharing live tenant event traffic with peer Enterprise orgs (Phase 9D), use client.Events.Custom.Federation instead — those types are prefixed EventFederation* to make the distinction unambiguous.

Audit

// Query audit logs
logs, err := client.Permissions.QueryAuditLogs(px.AuditLogQuery{
    AdminID:   "usr_123",
    Action:    "READ",
    StartDate: "2026-01-01T00:00:00Z",
    EndDate:   "2026-03-31T23:59:59Z",
    Limit:     50,
})

// Export audit logs
export, err := client.Permissions.ExportAuditLogs(px.AuditExportInput{
    StartDate: "2026-01-01T00:00:00Z",
    EndDate:   "2026-03-31T23:59:59Z",
    Format:    "csv",
})

---

client.Identity

Country-pluggable identity resolution + per-kind verifications across NG / KE / GH / ZA. The engine dispatches through the right per-country provider chain based on the identifier kind.

// Resolve identity (BVN, NIN, phone, etc.)
profile, err := client.Identity.Resolve("BVN", "22012345678", true, "ref_123")

// Generic verify (cross-country)
result, err := client.Identity.Verify("NIN", "12345678901", "Adaeze", "Okafor")

// Per-kind verifications (Phase 6F)
bvn, err := client.Identity.VerifyBVN(px.VerifyBVNRequest{
    SubjectID: "usr_001",
    BVN:       "22012345678",
    Match:     map[string]interface{}{"firstName": "Adaeze", "lastName": "Okafor"},
})
nin, err := client.Identity.VerifyNIN(px.VerifyNINRequest{ /* ... */ })
acct, err := client.Identity.VerifyAccount(px.VerifyAccountRequest{ /* ... */ })
live, err := client.Identity.Liveness(px.LivenessRequest{
    SubjectID: "usr_001",
    Image:     map[string]interface{}{"url": "https://example.com/selfie.jpg"},
})
face, err := client.Identity.FaceMatch(px.FaceMatchRequest{ /* ... */ })

// Provider health rollup (Phase 6F.5) — per-(country, provider)
// circuit-breaker state + latency p50/p95/p99
health, err := client.Identity.ProvidersHealth()

// Dead-letter queue (Phase 6F.5b)
dlq, err := client.Identity.Dlq.List(px.ListDlqParams{UnreplayedOnly: true})
stats, err := client.Identity.Dlq.Stats()
row, err := client.Identity.Dlq.Get("idlq_123")
replay, err := client.Identity.Dlq.Replay("idlq_123")

---

client.Messaging (7 methods)

Transactional email and (coming soon) SMS/WhatsApp.

// Send email
result, err := client.Messaging.SendEmail(px.SendEmailInput{
    To:      []string{"user@example.com"},
    Subject: "Order Confirmation",
    HTML:    "<h1>Order #1234 confirmed</h1>",
    ReplyTo: "support@example.com",
})

// Get email status
status, err := client.Messaging.GetEmailStatus("msg_abc123")

// List email queue
queue, err := client.Messaging.ListEmailQueue(px.EmailQueueFilter{
    Status: "pending",
    Limit:  20,
})

// Retry a failed email
err = client.Messaging.RetryEmail("msg_abc123")

---

client.Webhooks (7 methods)

Manage outbound webhook endpoints.

// Create webhook
webhook, err := client.Webhooks.Create(px.CreateWebhookInput{
    URL:    "https://example.com/webhooks",
    Events: []string{"email.sent", "email.bounced"},
    Secret: "whsec_your_signing_secret",
})

// List webhooks
webhooks, err := client.Webhooks.List()

// Get webhook
webhook, err := client.Webhooks.Get("wh_abc123")

// Update webhook
err = client.Webhooks.Update("wh_abc123", px.UpdateWebhookInput{
    URL: "https://example.com/webhooks/v2",
})

// Delete webhook
err = client.Webhooks.Delete("wh_abc123")

// Test webhook
err = client.Webhooks.Test("wh_abc123")

// Get webhook deliveries
deliveries, err := client.Webhooks.ListDeliveries("wh_abc123", 20)

---

client.Templates (7 methods)

Manage reusable content templates.

// Create template
template, err := client.Templates.Create(px.CreateTemplateInput{
    Name:      "welcome-email",
    Subject:   "Welcome to {{company}}",
    HTML:      "<h1>Welcome, {{name}}!</h1>",
    Variables: []string{"company", "name"},
})

// List templates
templates, err := client.Templates.List()

// Get template
template, err := client.Templates.Get("tmpl_abc123")

// Update template
err = client.Templates.Update("tmpl_abc123", px.UpdateTemplateInput{
    Subject: "Updated Subject",
})

// Delete template
err = client.Templates.Delete("tmpl_abc123")

// Render template (preview)
rendered, err := client.Templates.Render("tmpl_abc123", map[string]string{
    "company": "Acme",
    "name":    "Jane",
})

// List template versions
versions, err := client.Templates.ListVersions("tmpl_abc123")

---

client.Storage (10 methods)

File upload, retrieval, and management.

// Upload file
file, err := os.Open("invoice.pdf")
result, err := client.Storage.Upload(px.UploadInput{
    File:     file,
    Filename: "invoice.pdf",
    Folder:   "invoices",
    Access:   "private",
})

// Upload from URL
result, err := client.Storage.UploadFromURL(px.UploadFromURLInput{
    URL:      "https://example.com/image.png",
    Filename: "image.png",
    Folder:   "images",
})

// Get file metadata
meta, err := client.Storage.Get("file_abc123")

// List files
files, err := client.Storage.List(px.ListFilesInput{Folder: "invoices", Limit: 20})

// Delete file
err = client.Storage.Delete("file_abc123")

// Get signed URL
url, err := client.Storage.GetSignedURL("file_abc123", 3600) // expires in 1 hour

// Update file metadata
err = client.Storage.Update("file_abc123", px.UpdateFileInput{Folder: "archive"})

// Copy file
copy, err := client.Storage.Copy("file_abc123", "backup")

// Move file
err = client.Storage.Move("file_abc123", "processed")

// Get storage usage
usage, err := client.Storage.GetUsage()

---

client.Workflows (6 methods)

Event-driven workflow automation.

// Create workflow
workflow, err := client.Workflows.Create(px.CreateWorkflowInput{
    Name:    "New User Onboarding",
    Trigger: px.Trigger{Event: "user.created"},
    Actions: []px.Action{
        {Type: "send_email", TemplateID: "tmpl_welcome"},
        {Type: "webhook", URL: "https://example.com/onboard"},
    },
})

// List workflows
workflows, err := client.Workflows.List()

// Get workflow
workflow, err := client.Workflows.Get("wf_abc123")

// Update workflow
err = client.Workflows.Update("wf_abc123", px.UpdateWorkflowInput{
    Name: "Updated Onboarding",
})

// Delete workflow
err = client.Workflows.Delete("wf_abc123")

// Trigger workflow manually
err = client.Workflows.Trigger("wf_abc123", map[string]interface{}{
    "user_id": "usr_123",
})

---

client.Domains (5 methods)

Manage sending domains for email delivery.

// Add sending domain
domain, err := client.Domains.Create("mail.example.com")

// List domains
domains, err := client.Domains.List()

// Get domain (includes DNS records)
domain, err := client.Domains.Get("dom_abc123")

// Verify domain
result, err := client.Domains.Verify("dom_abc123")

// Delete domain
err = client.Domains.Delete("dom_abc123")

---

client.Subscriptions (8 methods)

Manage event subscriptions for real-time notifications.

// Create subscription
sub, err := client.Subscriptions.Create(px.CreateSubscriptionInput{
    Event: "email.sent",
    URL:   "https://example.com/events",
})

// List subscriptions
subs, err := client.Subscriptions.List()

// Get subscription
sub, err := client.Subscriptions.Get("sub_abc123")

// Update subscription
err = client.Subscriptions.Update("sub_abc123", px.UpdateSubscriptionInput{
    URL: "https://example.com/events/v2",
})

// Delete subscription
err = client.Subscriptions.Delete("sub_abc123")

// Pause subscription
err = client.Subscriptions.Pause("sub_abc123")

// Resume subscription
err = client.Subscriptions.Resume("sub_abc123")

// List subscription deliveries
deliveries, err := client.Subscriptions.ListDeliveries("sub_abc123")

---

client.Misc (7 methods)

Utility and account-level operations.

// Health check
health, err := client.Misc.Health()

// Get API key info
info, err := client.Misc.GetAPIKeyInfo()

// Get organization details
org, err := client.Misc.GetOrganization()

// Get usage summary
usage, err := client.Misc.GetUsage("2026-03")

// Generate PDF from HTML
pdf, err := client.Misc.GeneratePDF(px.GeneratePDFInput{
    HTML:    "<h1>Invoice #1234</h1>",
    Options: px.PDFOptions{Format: "A4", Margin: "20mm"},
})

// OCR - extract text from image
text, err := client.Misc.OCR("file_abc123")

// Verify identity document
result, err := client.Misc.VerifyDocument("file_abc123", "national_id")

---

client.Fraud (29 methods)

Full Phase 6 Detection Engine surface. See the SDK Fraud reference for the full method matrix.

verdict, err := client.Fraud.Decisions.Decide(px.FraudDecideRequest{
    Subject:  px.FraudDecideSubject{ID: "user_123", Kind: "user"},
    Action:   "withdraw",
    Resource: px.FraudDecideResource{Kind: "transaction"},
})

Sub-services: client.Fraud.Decisions, client.Fraud.Rules, client.Fraud.Lists, client.Fraud.Devices, client.Fraud.Cases, client.Fraud.Terms.

---

client.Audit (1 method)

Federated audit log dispatch. See the Audit reference.

_, err := client.Audit.Log(px.AuditLogRequest{
    App:        "lettings",
    ActorID:    "user_123",
    EntityType: "BOOKING",
    EntityID:   "bk_abc",
    Action:     "CONFIRMED",
})

---

client.Issues (2 methods)

Federated bug / support-ticket workflow. See the Issues reference.

issues, err := client.Issues.List(px.ListIssuesParams{App: "lettings", Status: "OPEN"})

created, err := client.Issues.Create(px.CreateIssueRequest{
    App:         "lettings",
    ReporterID:  "user_123",
    Title:       "Booking confirmation email shows wrong nights",
    Description: "Booked 3 nights, email says 2.",
    Priority:    "HIGH",
})

---

client.Search (2 methods)

Federated search index + query. See the Search reference.

_, err := client.Search.Index(px.SearchIndexRequest{
    App:        "lettings",
    EntityType: "PROPERTY",
    EntityID:   "prop_abc",
    Title:      "Lekki Penthouse",
    Keywords:   "lekki lagos penthouse 3 bedroom",
})

results, err := client.Search.Query("lekki", "lettings")

---

client.Whoami (1 method)

API key verification + boot-time self-check. See the Whoami reference.

me, err := client.Whoami.Get()
if err != nil { log.Fatal(err) }
fmt.Printf("Authenticated as %s (%s)\n", me.CallerService, me.OrganizationID)
if me.GracePeriodWarning != nil { log.Println(*me.GracePeriodWarning) }

---

platformxe.Register (package-level)

Unauthenticated bootstrap for new developers. Sits at the package root because it runs before you have an API key.

import px "github.com/calderax/platformxe-go"

r, err := px.Register(px.RegisterRequest{
    Name:  "Acme",
    Email: "dev@acme.test",
}, nil)
if err != nil { log.Fatal(err) }

client := px.NewClient(px.ClientConfig{APIKey: r.APIKey})
// Save r.APIKey — it cannot be retrieved again.

---

Error handling

import "errors"

result, err := client.Messaging.SendEmail(px.SendEmailInput{
    To:      []string{"user@example.com"},
    Subject: "Test",
    HTML:    "<p>Hi</p>",
})

if err != nil {
    var rateLimitErr *px.RateLimitError
    if errors.As(err, &rateLimitErr) {
        fmt.Printf("Rate limited. Retry after %ds\n", rateLimitErr.RetryAfter)
        return
    }

    var apiErr *px.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("Error %s: %s\n", apiErr.Code, apiErr.Message)
        return
    }

    log.Fatal(err)
}

See Error Handling for the full list of error codes.