Skip to content

API Access

Authentication & permissions

Floecat supports two client authentication modes:

  • Authorization header (Bearer token): pass --token (or FLOECAT_TOKEN). The token is sent as authorization: Bearer <token> by default. The server derives identity and account from token claims.
  • Session header (custom): pass --session-token (or FLOECAT_SESSION_TOKEN) and optionally set --session-header (default x-floe-session). This is functionally equivalent to authorization header auth but uses a custom header name.

How to tell if you have permission:

  • If a command succeeds, you have the required permission.
  • If it fails with PERMISSION_DENIED and a message like missing permission: <perm>, you do not have that permission for the current identity.

Fixed role names and their granted permissions are documented in docs/fixed-roles.md.

gRPC

Use any gRPC client (for example grpcurl) once the service listens on localhost:9100.

grpcurl -plaintext -d '{}' \
  localhost:9100 ai.floedb.floecat.catalog.CatalogService/ListCatalogs

If the server is configured for authorization-header auth (default header authorization):

grpcurl -plaintext \
  -H 'authorization: Bearer <TOKEN>' \
  -d '{}' localhost:9100 \
  ai.floedb.floecat.catalog.CatalogService/ListCatalogs

If the server is configured for session-header auth (default header x-floe-session):

grpcurl -plaintext \
  -H 'x-floe-session: <TOKEN>' \
  -d '{}' localhost:9100 \
  ai.floedb.floecat.catalog.CatalogService/ListCatalogs

grpcurl -plaintext -d '{
  "catalog_id": {"account_id":"5eaa9cd5-7d08-3750-9457-cfe800b0b9d2",
                 "id":"109c1761-323a-3f72-83da-ff4f89c3b581","kind":"RK_CATALOG"}
}' localhost:9100 ai.floedb.floecat.catalog.NamespaceService/ListNamespaces

grpcurl -plaintext -d '{
  "namespace_id": {"account_id":"5eaa9cd5-7d08-3750-9457-cfe800b0b9d2",
                   "id":"86853a0f-a999-3c72-9a81-6dc66d1923a2","kind":"RK_NAMESPACE"}
}' localhost:9100 ai.floedb.floecat.catalog.TableService/ListTables

CLI

The client-cli module provides an interactive shell with auto-completion and context-aware rendering. After building it (make cli or make cli-run), launch with:

java --enable-native-access=ALL-UNNAMED \
  -jar client-cli/target/quarkus-app/quarkus-run.jar

If you use bearer-token auth, provide it via --token or FLOECAT_TOKEN:

FLOECAT_TOKEN=<TOKEN> \
  java --enable-native-access=ALL-UNNAMED \
  -jar client-cli/target/quarkus-app/quarkus-run.jar

Then explore catalog, namespace, table, connector, and query commands. The CLI exercises the same gRPC surface described in service.md.