Authentication

The SDK supports three ways to authenticate. Pick based on where the code runs:

Flow	Best for	Needs
API key	Servers, CI, cron jobs (automation)	An lh_… key minted in the portal
Email/password	Apps with a traditional email login	Registered + verified email
SIWE	web3-native apps	An Ethereum wallet / signer

All snippets use these imports:

import (
    sdkclient "github.com/lighthouse-web3/baas-go-sdk/client"
    sdktypes  "github.com/lighthouse-web3/baas-go-sdk/types"
)

Point APIURL at the API host

The portal lives at baas.lighthouse.storage; the SDK talks to baas-api.lighthouse.storage. Always set APIURL: "https://baas-api.lighthouse.storage".

Use an API key for automation

For servers, CI, and cron jobs, mint an API key in the portal and use the API key flow below. It is the most reliable path. The interactive SIWE handshake depends on the /auth/nonce endpoint, which may return 404 on the production API — if you hit that, switch to an API key. See Troubleshooting.

1) API key (recommended for automation)

This is the simplest and most common flow for backup jobs. When you pass an APIKey, the client is already authenticated — you do not call Authenticate().

import (
    "log"
    "os"

    sdkclient "github.com/lighthouse-web3/baas-go-sdk/client"
)

func newClient() *sdkclient.BackupClient {
    c, err := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
        APIURL:      "https://baas-api.lighthouse.storage", // API host
        APIKey:      os.Getenv("LH_API_KEY"),               // lh_… from the portal
        WorkspaceID: os.Getenv("LH_WORKSPACE_ID"),          // workspace UUID
    })
    if err != nil {
        log.Fatalf("client init: %v", err)
    }
    return c
}

Switching workspaces: call c.SetWorkspaceID(id) to change the default, or pass WorkspaceID inside BackupOptions / RestoreOptions to override for a single call.

See API Keys for how to create, scope, and rotate keys.

2) Email/password flow

Use this when your app has a traditional email login.

A. Register (signup)

client, err := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
    APIURL: "https://baas-api.lighthouse.storage",
})
if err != nil {
    panic(err)
}

regResp, err := client.RegisterEmail("alice@example.com", "strong-password", "Alice")
if err != nil {
    panic(err)
}
_ = regResp // contains userId/message

B. Verify email

After registration, verify using the token from your email flow:

verifyResp, err := client.VerifyEmail(sdktypes.EmailVerifyRequest{
    Token: "<verification-token>",
})
if err != nil {
    panic(err)
}

// If the backend returns verifyResp.Token, the SDK stores it automatically.
_ = verifyResp

C. Login with email/password

client, err := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
    APIURL:   "https://baas-api.lighthouse.storage",
    Email:    "alice@example.com",
    Password: "strong-password",
})
if err != nil {
    panic(err)
}

authResp, err := client.AuthenticateEmail()
if err != nil {
    panic(err)
}
_ = authResp // token + user payload

3) SIWE flow

Use this when your app authenticates with an Ethereum wallet.

caution

The SIWE handshake calls POST /auth/nonce. On the production API this endpoint may return 404. If you only need credentials for a backup job, prefer a portal-minted API key instead of provisioning via SIWE.

A. Construct client with wallet signer

Using a private key directly:

client, err := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
    APIURL:     "https://baas-api.lighthouse.storage",
    PrivateKey: "<hex-private-key>",
})
if err != nil {
    panic(err)
}

Or provide a custom signer from your wallet integration:

client, err := sdkclient.NewBackupClient(sdkclient.BackupClientOptions{
    APIURL:  "https://baas-api.lighthouse.storage",
    Address: "0xYourWalletAddress",
    SignMessage: func(message string) (string, error) {
        // call your wallet sign API and return a 0x-prefixed signature
        return signWithWallet(message)
    },
})
if err != nil {
    panic(err)
}

B. Authenticate (SIWE handshake)

token, err := client.Authenticate()
if err != nil {
    panic(err)
}
_ = token

4) Linking identities (email + wallet on one account)

If already authenticated, you can attach another identity:

// Link email/password identity
_, err = client.LinkIdentity(sdktypes.LinkIdentityRequest{
    Provider:        "email_password",
    ProviderSubject: "alice@example.com",
    Password:        "strong-password",
})

// Link SIWE wallet identity (lowercase address)
_, err = client.LinkIdentity(sdktypes.LinkIdentityRequest{
    Provider:        "siwe",
    ProviderSubject: "0xyourwalletaddress",
})