API Keys

API keys are the credential your automation (cron, CI, servers) uses to talk to BaaS. Each key belongs to one workspace, carries a fixed set of scopes, and is shown in full only once.

The portal is the most reliable way to mint a key

Generating a key in the portal (point, click, copy) is the recommended path — especially because programmatic provisioning that relies on the SIWE handshake can fail on the production API. The SDK calls below assume you are already authenticated (with a portal key or another flow); see Authentication.

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

Scope cheat-sheet

Grant only what the integration needs:

Task	Required scope(s)
Backup	backup:write (and backup:read for dedup)
List / inspect snapshots	snapshots:read
Prune snapshots	snapshots:read + backup:write
Delete a snapshot	backup:write
Restore	restore:read, restore:write
Read profile / usage	user:read

If a call returns 403 / insufficient scope, mint a new key with the missing scope — keys are immutable once created.

Create a key

Create a dedicated key for your backup runner.

import "time"

expires := time.Now().AddDate(0, 3, 0).UTC().Format(time.RFC3339) // 3 months

keyResp, err := client.CreateAPIKey(sdktypes.APIKeyCreateRequest{
	Name:        "nightly-postgres-backup",
	WorkspaceID: workspaceID,
	Scopes: []string{
		sdktypes.ScopeBackupWrite,
		sdktypes.ScopeBackupRead,
		sdktypes.ScopeSnapshotsRead,
	},
	ExpiresAt: expires,
})
if err != nil {
	log.Fatal(err)
}

plain := keyResp.Plaintext()       // the raw lh_… key; store securely, returned once
prefix := keyResp.APIKey.KeyPrefix // safe-to-log prefix
id := keyResp.APIKey.APIKeyID      // id for later revoke
log.Printf("NEW API KEY (store now): %s (prefix=%s id=%s)", plain, prefix, id)

Response shape

CreateAPIKey returns an APIKeyCreateResponse. The plaintext key is keyResp.Plaintext(); the prefix, id, scopes, and expiry live on the nested keyResp.APIKey — e.g. keyResp.APIKey.KeyPrefix, not keyResp.KeyPrefix.

Store the plaintext key in a secrets manager or environment variable (e.g. LH_API_KEY). After this call you can only ever see its prefix again.

List API keys

keys, err := client.ListAPIKeys()
if err != nil {
	log.Fatal(err)
}
for _, k := range keys {
	log.Printf("apiKeyId=%s name=%s status=%s prefix=%s", k.APIKeyID, k.Name, k.Status, k.KeyPrefix)
}

Revoke an API key

err := client.DeleteAPIKey("add-your-api-key-id")
if err != nil {
	log.Fatal(err)
}

Rotation tips

• Give automation keys a hard ExpiresAt and rotate before expiry.
• One key per job/environment makes revocation blast-radius small.
• Because keys are immutable, "changing scopes" means creating a new key and revoking the old one.

For how scopes combine with workspace roles (the intersection rule), see Roles, scopes, and permissions.