---
title: "Go SDK installation"
description: "Install the pgbeam-go SDK, configure the client, authenticate, and learn the service-based access pattern with a full agent-gateway quickstart."
canonical: "https://pgbeam.com/docs/go-sdk"
last-updated: "2026-10-29T19:01:20.000Z"
---

# Go SDK installation

> Install the pgbeam-go SDK, configure the client, authenticate, and learn the service-based access pattern with a full agent-gateway quickstart.

URL: https://pgbeam.com/docs/go-sdk

The PgBeam Go SDK is the official client for the PgBeam control-plane API. It covers every API resource (projects and databases, plus the agent gateway: agent credentials, policy profiles, approvals, webhooks, anomalies, and audit logs), so you can provision safe, scoped Postgres access for AI agents from Go.

The module path is `go.pgbeam.com/sdk` (a vanity import that resolves to the public mirror). The package name is `pgbeam`.

## Installation

```bash
go get go.pgbeam.com/sdk
```

Requires Go 1.25 or newer. Import it as:

```go
import pgbeam "go.pgbeam.com/sdk"
```

## Client setup

```go
import pgbeam "go.pgbeam.com/sdk"

client := pgbeam.NewClient(&pgbeam.ClientOptions{
    APIKey:  "pbu_your_api_key",
    BaseURL: "https://api.pgbeam.com", // optional
})
```

## Constructor options

| Option       | Type                  | Description                                                                                                                                                 |
| ------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APIKey`     | `string`              | PgBeam API key (required). Account keys start with `pbu_`, organization keys with `pbo_`                                                                    |
| `BaseURL`    | `string`              | API base URL (default: `https://api.pgbeam.com`)                                                                                                            |
| `HTTPClient` | `*http.Client`        | Custom HTTP client for proxies, transports, etc.                                                                                                            |
| `Retry`      | `*pgbeam.RetryConfig` | Retry and backoff settings. `nil` uses the defaults (5 retries, 500ms initial delay, 120s total budget). See [Retries](/docs/go-sdk/error-handling#retries) |
| `Timeout`    | `time.Duration`       | Per-attempt timeout. `0` means 30s, a negative value disables it                                                                                            |

## Authentication

**Explicit key**

```go
client := pgbeam.NewClient(&pgbeam.ClientOptions{
    APIKey:  "pbu_your_api_key",
    BaseURL: "https://api.pgbeam.com",
})
```

**From environment**

```go
client := pgbeam.NewClient(&pgbeam.ClientOptions{
    APIKey:  os.Getenv("PGBEAM_API_KEY"),
    BaseURL: os.Getenv("PGBEAM_API_URL"),
})
```

See [API Keys](/docs/api-keys) for key creation and rotation.

## Usage pattern

The Go SDK uses service-based access, matching the TypeScript SDK's tag-based `api.projects.*`, `api.databases.*` pattern:

```go
// Projects: request bodies are passed by value
project, err := client.Projects.CreateProject(ctx, pgbeam.CreateProjectRequest{
    OrgId: "org_xxx",
    Name:  "production",
    Database: pgbeam.CreateDatabaseRequest{
        Host: "db.internal", Port: 5432, Name: "app",
    },
})
project, err = client.Projects.GetProject(ctx, "prj_xxx")

// Databases
db, err := client.Databases.GetDatabase(ctx, "prj_xxx", "db_xxx")

// Agent gateway
profiles, err := client.Policies.ListPolicyProfiles(ctx, "prj_xxx", nil)
cred, err := client.Agents.CreateAgentCredential(ctx, "prj_xxx", pgbeam.CreateAgentCredentialRequest{...})

// Platform
health, err := client.Platform.GetHealth(ctx)
```

Each service field on the client maps to an API tag:

| Service      | Go                  | Covers                                           |
| ------------ | ------------------- | ------------------------------------------------ |
| `Projects`   | `client.Projects`   | Projects, replicas, custom domains, cache rules  |
| `Databases`  | `client.Databases`  | Upstream database connections                    |
| `Policies`   | `client.Policies`   | Policy profiles (read-only, allowlists, masking) |
| `Agents`     | `client.Agents`     | Agent credentials, rotation, audit logs          |
| `Approvals`  | `client.Approvals`  | Held-statement approval requests                 |
| `Webhooks`   | `client.Webhooks`   | Webhook endpoints for gateway events             |
| `Anomalies`  | `client.Anomalies`  | Anomaly alerts                                   |
| `Migrations` | `client.Migrations` | Migration safety linting                         |
| `Analytics`  | `client.Analytics`  | Plans, usage, spend limits, insights             |
| `Platform`   | `client.Platform`   | Health, regions                                  |
| `Account`    | `client.Account`    | Account export, onboarding                       |

## Quickstart: provision an agent credential

This end-to-end example creates a read-only policy profile and issues a scoped agent credential against it. The connection string and MCP token are returned **once**, so capture them immediately.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    pgbeam "go.pgbeam.com/sdk"
)

func main() {
    ctx := context.Background()
    client := pgbeam.NewClient(&pgbeam.ClientOptions{
        APIKey: os.Getenv("PGBEAM_API_KEY"),
    })

    projectID := "prj_xxx"

    // 1. Create a read-only policy profile capped at 1000 rows per query.
    accessMode := pgbeam.PolicyProfileInputAccessModeReadOnly
    maxRows := 1000
    profile, err := client.Policies.CreatePolicyProfile(ctx, projectID, pgbeam.PolicyProfileInput{
        Name:       "analytics-readonly",
        AccessMode: &accessMode,
        MaxRows:    &maxRows,
    })
    if err != nil {
        log.Fatalf("create policy: %v", err)
    }

    // 2. Issue an agent credential enforced against that profile.
    principal := pgbeam.CreateAgentCredentialRequestPrincipalTypeAgent
    secrets, err := client.Agents.CreateAgentCredential(ctx, projectID, pgbeam.CreateAgentCredentialRequest{
        Name:            "claude-analytics",
        PolicyProfileId: profile.Id,
        PrincipalType:   &principal,
    })
    if err != nil {
        log.Fatalf("create credential: %v", err)
    }

    // Shown once: hand these to the agent now.
    fmt.Println("Connection string:", secrets.ConnectionString)
    fmt.Println("MCP URL:          ", secrets.McpUrl)
    fmt.Println("MCP token:        ", secrets.McpToken)
}
```

## Examples across the surface

### List and inspect policy profiles

```go
profiles, err := client.Policies.ListPolicyProfiles(ctx, projectID, nil)
if err != nil {
    log.Fatal(err)
}
for _, p := range profiles.Policies {
    fmt.Printf("%s (%s): access=%s\n", p.Name, p.Id, p.AccessMode)
}
```

### Rotate or revoke an agent credential

```go
// Rotate: returns fresh secrets, the old credential stops working.
rotated, err := client.Agents.RotateAgentCredential(ctx, projectID, "agt_xxx")

// Revoke: immediate kill-switch.
err = client.Agents.RevokeAgentCredential(ctx, projectID, "agt_xxx")
```

### Approve a held statement

When a policy holds a write for approval, decide on it from the approvals service:

```go
reason := "verified against ticket OPS-1234"
approved, err := client.Approvals.ApproveApprovalRequest(ctx, projectID, "apr_xxx",
    pgbeam.ApprovalDecisionRequest{Reason: &reason})
```

### Register a webhook endpoint

```go
enabled := true
secret := "whsec_..." // signs delivery payloads
events := []string{"approval.requested", "anomaly.detected"}
hook, err := client.Webhooks.CreateWebhookEndpoint(ctx, projectID, pgbeam.WebhookEndpointInput{
    Url:        "https://example.com/pgbeam/events",
    Enabled:    &enabled,
    EventTypes: &events,
    Secret:     &secret,
})
```

### Page through the audit log

```go
event := "blocked"
logs, err := client.Agents.ListAuditLogs(ctx, projectID, &pgbeam.ListAuditLogsParams{
    Event: &event,
})
if err != nil {
    log.Fatal(err)
}
for _, e := range logs.Entries {
    fmt.Printf("%s %s rule=%v\n", e.Event, e.Id, e.DecisionRule)
}
```

For the per-method reference (every parameter, response type, and error code), see the service pages in the sidebar. For error handling, retries, and idempotency, see [Error Handling](/docs/go-sdk/error-handling).