API keys

Your applications reach a database with an API key: a key and a secret sent in two headers. You manage databases, API keys and owners in the InceptionDB console, signed in with your hola.cloud account.

Create a database

In the console, open the database selector and choose New database. It is ready in about a second. Its ID is on the overview page: that is the value of INCEPTIONDB_DATABASE.

Create an API key

Choose the database and open API keys & settings.
Click New API key and name it after the application that will use it, like backend-production.
Copy the secret. It is shown only once: InceptionDB stores only a hash of it.

The console gives you the credentials ready to use, for example as environment variables:

1export INCEPTIONDB_DATABASE="your-database-id"
2export INCEPTIONDB_API_KEY="your-api-key"
3export INCEPTIONDB_API_SECRET="your-api-secret"

An API key reaches every collection of its database, and only that database.

Use it

Send the key and the secret in the Api-Key and Api-Secret headers of every request:

curl "https://inceptiondb.hola.cloud/v1/databases/$INCEPTIONDB_DATABASE/collections" \
  -H "Api-Key: $INCEPTIONDB_API_KEY" \
  -H "Api-Secret: $INCEPTIONDB_API_SECRET"

GET /v1/databases/$INCEPTIONDB_DATABASE/collections HTTP/1.1
Host: inceptiondb.hola.cloud
Api-Key: $INCEPTIONDB_API_KEY
Api-Secret: $INCEPTIONDB_API_SECRET

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://inceptiondb.hola.cloud/v1/databases/" + os.Getenv("INCEPTIONDB_DATABASE") + "/collections", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Api-Key", os.Getenv("INCEPTIONDB_API_KEY"))
	req.Header.Set("Api-Secret", os.Getenv("INCEPTIONDB_API_SECRET"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(responseBody))
}

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://inceptiondb.hola.cloud/v1/databases/' . getenv('INCEPTIONDB_DATABASE') . '/collections',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Api-Key: ' . getenv('INCEPTIONDB_API_KEY'),
        'Api-Secret: ' . getenv('INCEPTIONDB_API_SECRET'),
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new Exception(curl_error($ch));
}
curl_close($ch);

echo $response;

import os
import requests

headers = {
    "Api-Key": os.environ["INCEPTIONDB_API_KEY"],
    "Api-Secret": os.environ["INCEPTIONDB_API_SECRET"],
}

response = requests.request(
    "GET",
    "https://inceptiondb.hola.cloud/v1/databases/" + os.environ["INCEPTIONDB_DATABASE"] + "/collections",
    headers=headers
)

print(response.text)

const response = await fetch("https://inceptiondb.hola.cloud/v1/databases/" + process.env.INCEPTIONDB_DATABASE + "/collections", {
  method: "GET",
  headers: {
    "Api-Key": process.env.INCEPTIONDB_API_KEY,
    "Api-Secret": process.env.INCEPTIONDB_API_SECRET
  }
});

console.log(await response.text());

// Fill in your values. Never put an API secret in code that runs in a public web page.
const INCEPTIONDB_DATABASE = "your-inceptiondb-database";
const INCEPTIONDB_API_KEY = "your-inceptiondb-api-key";
const INCEPTIONDB_API_SECRET = "your-inceptiondb-api-secret";

const response = await fetch("https://inceptiondb.hola.cloud/v1/databases/" + INCEPTIONDB_DATABASE + "/collections", {
  method: "GET",
  headers: {
    "Api-Key": INCEPTIONDB_API_KEY,
    "Api-Secret": INCEPTIONDB_API_SECRET
  }
});

const text = await response.text();
console.log(text);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://inceptiondb.hola.cloud/v1/databases/" + System.getenv("INCEPTIONDB_DATABASE") + "/collections"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .header("Api-Key", System.getenv("INCEPTIONDB_API_KEY"))
            .header("Api-Secret", System.getenv("INCEPTIONDB_API_SECRET"))
            .build();

        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

1[{"defaults":{"id":"uuid()"},"indexes":0,"name":"customers","total":3}]

A wrong key or secret answers 403 Forbidden.

Keep it safe

Keep the secret on your server, in environment variables or in a secret manager. Never in the code, in a repository or in a web page or mobile app: anyone who sees it can read and change your data.
Use one API key per application or environment. You can then revoke one without affecting the others.
If a secret leaks, create a new key, deploy it, and revoke the old one in API keys & settings. Revoked keys stop working at once.

Owners

Owners are the hola.cloud users who manage a database from the console: its collections, API keys and other owners. Add or remove them in API keys & settings. A database always keeps at least one owner, and you cannot remove yourself.

Account operations and the API

Creating, renaming and deleting databases, managing API keys and owners are done in the console. They are HTTP endpoints too (see the API reference), but they need the session of a signed-in user: an API key cannot call them. Every action of the console shows its request: click the balls on the right of the screen.