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

  1. Choose the database and open API keys & settings.
  2. Click New API key and name it after the application that will use it, like backend-production.
  3. 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
// Go 1.21+, standard library only. Save as main.go and run: go run main.go
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(resp.Status)
	fmt.Println(string(responseBody))
}
<?php
// PHP 8+ with the curl extension. Save as example.php and run: php example.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));
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $response, "\n";
curl_close($ch);
# Python 3.8+. Install: pip install requests. Save as example.py and run: python example.py
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.status_code)
print(response.text)
// Node.js 18+. Save as example.mjs and run: node example.mjs
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(response.status);
console.log(await response.text());
// Java 17+, standard library only. Save as Main.java and run: java Main.java
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.statusCode());
        System.out.println(response.body());
    }
}
1[{"defaults":{"id":"uuid()"},"indexes":0,"name":"customers","total":2}]

A wrong key or secret answers 403 Forbidden.

Keep it safe

  • InceptionDB is a server-to-server API. Do not call it from code that runs in a browser or a mobile app: anyone can read the secret there. If a web page needs data, have it call your own backend, which keeps the secret and calls InceptionDB.
  • 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: console only

Creating, renaming and deleting databases, and managing API keys and owners, are done in the console. The API reference lists their endpoints to explain what the console does, but they are not meant for automation:

  • Api-Key and Api-Secret do not work on them. An API key works only with the collections of its database.
  • They need the session of a user signed in to the console, and there is no supported way to get one outside the console.

See the code of a console action

Every action in the console is an HTTP request, and the console shows how to make it from your code. Click API calls, with the { } icon, at the bottom of the side menu. It lists the latest requests; choose one to see it in curl, Go, Python and the other languages, ready to copy. Each new request also appears as a coloured dot in the narrow column at the right edge of the console; clicking a dot opens the same view.

Comments

Leave a comment