Skip to content

Getting Started — Developers

Build applications against Gridone's HTTP API using an existing instance or a local development installation. You do not need access to Gridone's source code to use its API.

Before you begin

For an existing instance, ask its administrator for the instance URL and an account with the permissions your application needs, then continue at Authenticate. Use that instance's HTTPS URL instead of http://localhost:8765 in the examples.

For a local installation, you'll need Docker, Docker Compose, and read access to AGRID's private gridone-core container package. Contact AGRID to arrange installation access.

Once your GitHub account has package access, log in with your GitHub login and a dedicated personal access token (classic) with read:packages. Enter the token at Docker's password prompt:

docker login ghcr.io --username YOUR_GITHUB_LOGIN

Run Docker login and Compose as the same user, with the same DOCKER_CONFIG if you set one. Registry credentials stay in Docker's client configuration; do not put the registry token in the Compose file or application environment.


1. Start the stack

Create a docker-compose.yml:

services:
  timescaledb:
    image: timescale/timescaledb:latest-pg18
    container_name: timescaledb
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - timescaledb_data:/var/lib/postgresql/data

  gridone-app:
    image: ghcr.io/agrid-dev/gridone-core:latest
    container_name: gridone-app
    ports:
      - 8765:8765
    environment:
      STORAGE_URL: postgresql://postgres:postgres@timescaledb:5432/postgres
      GRIDONE_ADMIN_PASSWORD: ${GRIDONE_ADMIN_PASSWORD:?Set the initial admin password}
      COOKIE_SECURE: "false" # Local development over plain HTTP only
      GRIDONE_TIMEZONE: Europe/Paris
    restart: unless-stopped
    depends_on:
      - timescaledb

volumes:
  timescaledb_data:

Set GRIDONE_ADMIN_PASSWORD in your shell environment or a local .env file before starting Compose. It is read only on the first start against an empty database, to seed the admin account; the server refuses to start without it when no users exist yet. This password is separate from the registry token.

Replace Europe/Paris with your building's IANA timezone name (e.g. America/New_York, Asia/Tokyo). GRIDONE_TIMEZONE defaults to UTC if unset.

Then download the private image and start both services:

docker compose pull gridone-app
docker compose up

Once both containers are healthy:

  • http://localhost:8765 — UI in your browser
  • http://localhost:8765/api — HTTP API (see API Reference)

Schema migrations run automatically before the server starts.


2. Authenticate

The API uses OAuth2 password grant. Send credentials as a form body:

curl -X POST http://localhost:8765/api/auth/token \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=YOUR_GRIDONE_USERNAME" \
  --data-urlencode "password=YOUR_GRIDONE_PASSWORD"

Replace the placeholders with your Gridone account credentials. On a fresh local installation, use admin and the password configured in GRIDONE_ADMIN_PASSWORD.

Response:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "expires_in": 1800
}

Pass the access_token as a bearer token on every subsequent request:

Authorization: Bearer <access_token>

A system that calls the API on its own (an integration, a scheduled job) uses a service key instead: an administrator creates a service account and issues a key from the Users page, and the key is sent the same way, with no sign-in exchange:

Authorization: Bearer gd_sk_...

See service accounts and keys.


3. Verify Gridone is up

curl http://localhost:8765/api/health
{"status": "ok", "version": "vX.Y.Z", "flags": []}

Next steps

  • API Reference — full endpoint documentation, try requests directly from the browser
  • Integrator track — connect your first device (register a driver, add a device, verify live data)