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 browserhttp://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)