adminkey

convex-admin-key

A Go library for generating admin keys for Convex self-hosted backend instances.

Overview

This package generates admin keys compatible with the Convex backend's keybroker module. Keys are generated using:

• AES-128-GCM-SIV - Authenticated encryption with nonce-misuse resistance (RFC 8452)
• KBKDF-CTR-HMAC-SHA256 - NIST SP 800-108 Key Derivation Function in Counter Mode

This is a pure Go implementation that produces keys identical to the official Rust implementation.

Installation

go get github.com/ozanturksever/convex-admin-key

Library Usage

package main

import (
    "fmt"
    "log"

    adminkey "github.com/ozanturksever/convex-admin-key"
)

func main() {
    // Generate a new random instance secret
    secret, err := adminkey.GenerateSecret()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Instance secret: %s\n", secret.String())

    // Or parse an existing secret (64-character hex string)
    secret, err = adminkey.ParseSecret("4361726e697461732c206c69746572616c6c79206d65616e696e6720226c6974")
    if err != nil {
        log.Fatal(err)
    }

    // Issue a standard admin key
    key, err := adminkey.IssueAdminKey(secret, "my-instance", 0, false)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Admin key: %s\n", key)

    // Issue a read-only admin key
    readOnlyKey, err := adminkey.IssueAdminKey(secret, "my-instance", 0, true)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Read-only key: %s\n", readOnlyKey)

    // Issue a system key (for internal Convex operations)
    systemKey, err := adminkey.IssueSystemKey(secret, "my-instance")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("System key: %s\n", systemKey)
}

CLI Tool

You can also install and use the command-line tool:

go install github.com/ozanturksever/convex-admin-key/cmd/convex-admin-key@latest

Generate a new instance secret

convex-admin-key generate-secret

Generate an admin key

# Standard admin key
convex-admin-key admin-key <instance-name> <instance-secret>

# With member ID
convex-admin-key admin-key <instance-name> <instance-secret> --member-id 42

# Read-only key
convex-admin-key admin-key <instance-name> <instance-secret> --read-only

# System key
convex-admin-key admin-key <instance-name> <instance-secret> --system-key

# Quiet mode (for scripting)
convex-admin-key admin-key <instance-name> <instance-secret> -q

Example with Convex dev instance

# The dev instance uses "carnitas" with the following secret
convex-admin-key admin-key carnitas 4361726e697461732c206c69746572616c6c79206d65616e696e6720226c6974

API Reference

Types

Secret

A 32-byte instance secret used for key derivation.

type Secret [32]byte

Functions

GenerateSecret() (Secret, error)

Generates a new cryptographically random 32-byte secret.

ParseSecret(s string) (Secret, error)

Parses a 64-character hex string into a Secret.

(Secret) String() string

Returns the hex-encoded representation of the secret.

IssueAdminKey(secret Secret, instanceName string, memberID uint64, isReadOnly bool) (string, error)

Generates an admin key for the specified instance.

• secret: The instance secret
• instanceName: Name of the Convex instance (e.g., "carnitas")
• memberID: Member ID (use 0 for generic admin keys)
• isReadOnly: If true, creates a read-only key that can only run queries

IssueSystemKey(secret Secret, instanceName string) (string, error)

Generates a system key for internal Convex operations.

Key Format

Admin keys are formatted as <instance_name>|<encrypted_part> where the encrypted part is a hex-encoded blob containing:

1. Version byte (1)
2. 12-byte random nonce
3. Encrypted protobuf payload (issued timestamp, identity, read-only flag)
4. 16-byte authentication tag

Compatibility

This implementation is fully compatible with:

• Convex self-hosted backend instances
• The official Rust gen-admin-key tool
• The Convex backend's keybroker module

The KBKDF implementation matches aws-lc-rs exactly, ensuring keys generated by this library work with the Convex backend.

License

MIT License - see LICENSE for details.