---
title: Providers
url: /sdks/go/0.1.8/api/providers/
docset: sdk-go
version: 0.1.8
latest_version: 0.1.8
source: ai-openshell/sdk-go@v0.1.8:docs/src/api/providers.md
---

> Documentation index: /sdks/go/0.1.8/llms.txt. This page is for Go SDK 0.1.8.

# Providers

Accessor: `client.Providers()`

Register and manage compute providers (AI inference endpoints). Exposes
sub-clients for [Profiles](/sdks/go/0.1.8/api/profiles/) and [Refresh](/sdks/go/0.1.8/api/refresh/).

## Create

Register a new provider with the gateway.

```go
provider, err := client.Providers().Create(ctx, "default", &v1.Provider{
    Name: "my-openai",
    Type: "openai",
    Spec: v1.ProviderSpec{
        Credentials: map[string]string{
            "api_key": "sk-...",
        },
        Config: map[string]string{
            "base_url": "https://api.openai.com/v1",
        },
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Created provider:", provider.Name)
```

## Get

Fetch a provider by name.

```go
provider, err := client.Providers().Get(ctx, "default", "my-openai")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Provider type:", provider.Type)
```

## List

`List` returns a lazy pager over registered providers. `ListAll` follows every
continuation token; `PageSize` controls each request.

```go
// List all providers
providers, err := client.Providers().ListAll(ctx, "default")
if err != nil {
    log.Fatal(err)
}
for _, p := range providers {
    fmt.Println(p.Name, p.Type)
}

// With a smaller page size
providers, err = client.Providers().ListAll(ctx, "default", v1.ListOptions{
    PageSize: 10,
})

// Platform Admin only: list across all workspaces
allProviders, err := client.Providers().ListAll(ctx, "", v1.ListOptions{
    AllWorkspaces: true,
})
```

## Update

Update an existing provider's configuration or credentials.

```go
provider, err := client.Providers().Get(ctx, "default", "my-openai")
if err != nil {
    log.Fatal(err)
}

provider.Spec.Credentials["api_key"] = "sk-new-key"
updated, err := client.Providers().Update(ctx, "default", provider)
if err != nil {
    log.Fatal(err)
}
fmt.Println("Updated provider:", updated.Name)
```

## Delete

Remove a provider by name.

```go
deletion, err := client.Providers().Delete(ctx, "default", "my-openai")
if err != nil {
    log.Fatal(err)
}
```

## Ensure

Create or update a provider in a single idempotent call. If a provider with the given name exists, it is updated; otherwise a new one is created. This is the recommended way to register providers because it avoids "already exists" errors when re-registering.

```go
provider, err := client.Providers().Ensure(ctx, "default", &v1.Provider{
    Name: "my-openai",
    Type: "openai",
    Spec: v1.ProviderSpec{
        Credentials: map[string]string{
            "api_key": "sk-...",
        },
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("Provider ready:", provider.Name)
```

Ensure is an SDK-level convenience. It calls `GetProvider` first, then either `CreateProvider` or `UpdateProvider` depending on whether the provider already exists.

## Sub-Clients

The `ProviderInterface` exposes two sub-client accessors for related operations. These are pure client-side accessors with no corresponding gRPC call.

### Profiles

`client.Providers().Profiles()` returns a [ProfileInterface](/sdks/go/0.1.8/api/profiles/) for managing provider type profiles. Profiles define templates and defaults for different provider types.

### Refresh

`client.Providers().Refresh()` returns a [RefreshInterface](/sdks/go/0.1.8/api/refresh/) for configuring credential refresh strategies. Use it to set up automatic credential rotation for providers with expiring credentials.

## Provider

The `Provider` type represents a registered compute provider.

| Field             | Type               | Description                                 |
| ----------------- | ------------------ | ------------------------------------------- |
| `ID`              | string             | Server-assigned unique identifier           |
| `Name`            | string             | User-chosen name (unique per gateway)       |
| `Type`            | string             | Provider type (e.g., `"openai"`, `"azure"`) |
| `CreatedAt`       | time.Time          | Timestamp of creation                       |
| `Labels`          | map\[string]string | Key-value metadata labels                   |
| `ResourceVersion` | uint64             | Optimistic concurrency version              |
| `Spec`            | ProviderSpec       | Configuration and credentials               |

## ProviderSpec

`ProviderSpec` holds provider-specific configuration and credentials.

| Field                 | Type                  | Description                                 |
| --------------------- | --------------------- | ------------------------------------------- |
| `Credentials`         | map\[string]string    | Authentication credentials (e.g., API keys) |
| `Config`              | map\[string]string    | Provider-specific configuration values      |
| `CredentialExpiresAt` | map\[string]time.Time | Expiration timestamps for credentials       |

The curated Go API uses a zero `time.Time` value to clear an expiration during
an update. Consequently, it cannot represent the protobuf minimum timestamp
(`0001-01-01T00:00:00Z`) in this map. Use the raw protobuf API if that exact
timestamp is required. Other pointer-based timestamp fields preserve it.

See also: [Profiles](/sdks/go/0.1.8/api/profiles/), [Refresh](/sdks/go/0.1.8/api/refresh/), [Error Handling](/sdks/go/0.1.8/error-handling/), [Testing](/sdks/go/0.1.8/testing/)
