> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xkey.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with the Go SDK

> Install github.com/0xkey-io/sdk-go, configure API keys, and make your first authenticated request.

## Overview

The official Go module [`github.com/0xkey-io/sdk-go`](https://pkg.go.dev/github.com/0xkey-io/sdk-go) provides:

* Generated API client (go-swagger) for 0xkey activities
* API key generation and request signing (`pkg/apikey`)
* HPKE enclave encryption for OTP and import/export (`pkg/enclave_encrypt`)
* Session JWT verification (`pkg/crypto`)
* Local key storage (`pkg/store/local`)

Use it for **server-side** automation: Company Wallets, delegated access, OTP backends, and batch signing.

***

## Prerequisites

1. **Go 1.21+**
2. A 0xkey organization ([Quickstart](/getting-started/quickstart))
3. An API keypair registered to that organization (private key stays on your machine)

Generate and register keys with the [`examples/apikey`](https://github.com/0xkey-io/sdk-go/tree/main/examples/apikey) helper. A standalone `0xkey` CLI is **Coming soon**.

***

## Installation

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
go get github.com/0xkey-io/sdk-go@latest
```

Current release: [`v0.1.0`](https://github.com/0xkey-io/sdk-go/releases) on [pkg.go.dev](https://pkg.go.dev/github.com/0xkey-io/sdk-go).

***

## Configure API keys

The SDK reads keys from **`~/.config/0xkey/keys/`** when you pass `sdk.WithAPIKeyName("default")`.

After creating a key with the CLI, ensure the key name matches what you pass to `WithAPIKeyName`. Alternatively, load a key programmatically:

```go theme={"theme":{"light":"github-light","dark":"github-dark"}}
import "github.com/0xkey-io/sdk-go/pkg/apikey"

key, err := apikey.FromZeroXKeyPrivateKey(
	os.Getenv("OXKEY_API_PRIVATE_KEY"),
	apikey.SchemeP256,
)
```

***

## First request (Whoami)

```go theme={"theme":{"light":"github-light","dark":"github-dark"}}
package main

import (
	"fmt"
	"log"

	"github.com/0xkey-io/sdk-go"
	"github.com/0xkey-io/sdk-go/pkg/api/client/sessions"
	"github.com/0xkey-io/sdk-go/pkg/api/models"
)

func main() {
	client, err := sdk.New(sdk.WithAPIKeyName("default"))
	if err != nil {
		log.Fatal(err)
	}

	params := sessions.NewGetWhoamiParams().WithBody(&models.GetWhoamiRequest{
		OrganizationID: client.DefaultOrganization(),
	})

	resp, err := client.V0().Sessions.GetWhoami(params, client.Authenticator)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("UserID:", *resp.Payload.UserID)
}
```

Runnable copy: [`examples/whoami`](https://github.com/0xkey-io/sdk-go/tree/main/examples/whoami).

***

## Custom API host

For staging or local-gateway:

```go theme={"theme":{"light":"github-light","dark":"github-dark"}}
import "github.com/0xkey-io/sdk-go/pkg/api/client"

cfg := client.DefaultTransportConfig()
cfg.Host = "api.0xkey.com" // local-gateway
cfg.Schemes = []string{"https"}

c, err := sdk.New(
	sdk.WithAPIKeyName("default"),
	sdk.WithTransportConfig(*cfg),
)
```

Local HTTP (no TLS):

```go theme={"theme":{"light":"github-light","dark":"github-dark"}}
cfg.Host = "localhost:8080"
cfg.Schemes = []string{"http"}
```

Enclave-backed flows (email OTP) also need signer/notarizer public keys — see [`examples/email_otp`](https://github.com/0xkey-io/sdk-go/tree/main/examples/email_otp).

***

## Sub-packages

| Package               | Purpose                                             |
| :-------------------- | :-------------------------------------------------- |
| `pkg/apikey`          | P-256 / Ed25519 key generation and stamps           |
| `pkg/enclave_encrypt` | HPKE encrypt to Signer enclave (OTP, import/export) |
| `pkg/crypto`          | Session JWT and OTP token verification              |
| `pkg/encryptionkey`   | Encryption key helpers                              |
| `pkg/proofs`          | Nitro attestation verification                      |
| `pkg/store/local`     | Filesystem key storage                              |
| `pkg/api/client`      | Low-level generated client                          |

Import sub-packages independently when you do not need the full `sdk.New()` wrapper.

***

## Example workflows

| Example          | Path                                        | Description                    |
| :--------------- | :------------------------------------------ | :----------------------------- |
| Whoami           | `examples/whoami/`                          | Verify API key and org         |
| Email OTP        | `examples/email_otp/`                       | Full backend OTP + HPKE flow   |
| Delegated access | `examples/delegated_access/`                | Sub-org + scoped policy        |
| Sign transaction | `examples/signing/sign_transaction/`        | Activity signing               |
| Sign raw payload | `examples/signing/sign_raw_payload/`        | Message signing                |
| Ethereum txs     | `examples/transaction_management/ethereum/` | EVM transaction management     |
| Solana txs       | `examples/transaction_management/solana/`   | SVM transaction management     |
| go-ethereum      | `examples/go-ethereum/`                     | BindSigner integration         |
| Wallet CRUD      | `examples/wallets/`                         | Create, import, export wallets |
| API key gen      | `examples/apikey/`                          | Programmatic key creation      |

***

## Error handling

API errors can be inspected as `*runtime.APIError`:

```go theme={"theme":{"light":"github-light","dark":"github-dark"}}
import (
	"io"
	"github.com/go-openapi/runtime"
)

if err != nil {
	if apiErr, ok := err.(*runtime.APIError); ok && apiErr.Response != nil {
		b, _ := io.ReadAll(apiErr.Response.Body())
		log.Printf("0xkey API body: %s", string(b))
	}
	return err
}
```

Custom logging: `sdk.WithLogger(yourLogger)` — see [Go SDK overview](/sdks/go/landing).

***

## Next steps

<CardGroup cols={2}>
  <Card title="Delegated access" icon="shield" href="/concepts/policies/delegated-access-backend">
    Policy-scoped backend signing
  </Card>

  <Card title="TypeScript server" icon="node-js" href="/sdks/javascript-server">
    Node.js equivalent of server automation
  </Card>

  <Card title="API stamps" icon="key" href="/developer-reference/api-overview/stamps">
    How requests are authenticated
  </Card>

  <Card title="pkg.go.dev" icon="book" href="https://pkg.go.dev/github.com/0xkey-io/sdk-go">
    Generated API reference
  </Card>
</CardGroup>