Connection & Authentication

RogueDB operates on a strict Zero Trust architecture. We do not support unauthenticated endpoints, local dev-mode workarounds, or plaintext connections. Every request to the engine must be cryptographically verified and routed over HTTPS/TLS.

Because RogueDB is a zero-configuration engine, TLS is handled automatically by our public certificates. You simply point your client to your provisioned URL, attach your credentials, and execute.

1. Your Provisioned Credentials

Upon creating a RogueDB instance, three critical items are delivered to your admin email and securely vaulted in your customer portal:

Instance URL

customer.roguedb.dev

Your dedicated, globally routed engine endpoint.

x509 Certificate

The cryptographic certificate used to generate your JSON Web Tokens (JWTs).

Master API Key

Your immutable Super Admin identity key with unrestricted access and cannot be deleted.

The Principle of Least Privilege (User API Keys)

RogueDB enforces whitelisting per schema for access controls. Use your Master API Key only for initial creation of admin Users. For all other activity, use scoped User API Keys with restricted, granular privileges that use least-privilege access.

2. The Two-Tiered Security Contract

To maximize network performance and guarantee native HIPAA/SOC2 compliance logging, RogueDB splits security into two distinct layers. Both layers are required for every request.

Tier 1: Network-Level Authorization (Headers)

Every request must include a valid JWT in the connection metadata/headers. If this is missing or invalid, the request is instantly rejected at the network edge (401 Unauthorized) before the payload is ever parsed. This protects your database from unauthorized traffic.

Tier 2: Engine-Level Identification (Payload)

RogueDB handles compliance logging natively for performance and simplicity (future feature), your API Key (either the Master Key for setup, or a scoped User Key for production) is provided directly in your Protobuf or JSON payload. This strictly binds the requester's identity to the request for auditing, identification, and authorization checks.

3. Establsing a Connection

Inject your JWT into call metadata and pass your API key in the Protobuf message.

C++

Python

std::string createJwt()
{
    // Values found in service_account.json.
    const std::string SERVICE_ACCOUNT_EMAIL{ "YOUR_SERVICE_ACCOUNT_EMAIL" };
    const std::string PRIVATE_KEY_ID{ "YOUR_PRIVATE_KEY_ID" };
    const std::string PRIVATE_KEY{ "YOUR_PRIVATE_KEY" };
    const auto now{ std::chrono::system_clock::now() };
    return std::string{ jwt::create()
        .set_issuer(SERVICE_ACCOUNT_EMAIL)
        .set_subject(SERVICE_ACCOUNT_EMAIL)
        .set_audience(std::format(
        	"{}.roguedb.dev", 
            SERVICE_ACCOUNT_EMAIL.substr(
            	0, SERVICE_ACCOUNT_EMAIL.find("@"))))
        .set_issued_at(now)
        .set_expires_at(now + std::chrono::hours(1))
        .set_header_claim("kid", jwt::claim(PRIVATE_KEY_ID))
        .sign(jwt::algorithm::rs256{ PRIVATE_KEY }) };
}

const std::string API_KEY{ "YOUR_API_KEY" };
const std::string URL{ "[DATABASE_URL].roguedb.dev" };
const std::string ENCODED_JWT{ createJwt() };

std::unique_ptr<rogue::services::RogueDB::Stub> roguedb{ rogue::services::RogueDB::NewStub(
grpc::CreateChannel(
    std::format("{}:443", URL),
    grpc::SslCredentials(grpc::SslCredentialsOptions()))) };
        
grpc::ClientContext context{};
context.AddMetadata("Authorization", std::format("Bearer {}", ENCODED_JWT));

// Example Bidirectional Stream (eg. CRUD APIs)
auto stream{ roguedb->insert(&context) };

// Example Unary Stream (eg. non-CRUD APIs)
roguedb->subscribe(&context, subscribe, &response);

Next Steps

With your credentials verified and your connection established, you are ready to define your data structure.

Schema Definition

On This Page

Introduction to RogueDB

How to Use These Docs

The Mental Model