Get started

Authenticate with your API key

Send your GeotechOS API key as a bearer token on every request, and check it with whoami before you write.

Every request sends the API key in the Authorization header as a bearer token. The key names your workspace by itself. You do not send a workspace id.

Headers

Send these headers on every request:

Authorization: Bearer <your API key>
Accept: application/json
Content-Type: application/json

Always use HTTPS. The key works like a password.

Check your key

GET /whoami tells you which integration the key belongs to and what it can do. Call it before you write. Call it again when a request is refused for no clear reason.

export GEOTECHOS_URL="https://au.geotechos.com/api/integration/v1"
export GEOTECHOS_API_KEY="<your API key>"

curl -s "$GEOTECHOS_URL/whoami" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json"

The same in Python, with requests:

import os
import requests

answer = requests.get(
    f"{os.environ['GEOTECHOS_URL']}/whoami",
    headers={"Authorization": f"Bearer {os.environ['GEOTECHOS_API_KEY']}", "Accept": "application/json"},
    timeout=20,
)
print(answer.status_code, answer.json())

The answer:

{
  "integration": {
    "uuid": "01a1b2c3-…",
    "name": "Website job requests",
    "provider": "website",
    "assigns_project_numbers": false,
    "adds_staff_accounts": false
  },
  "workspace": { "name": "Example Geotechnical", "timezone": "UTC" },
  "acting_as": { "uuid": "01a1b2c4-…", "name": "Website Integration" },
  "granted_abilities": ["clients:view", "clients:edit", "projects:view", "projects:edit", "jobs:view", "jobs:edit"],
  "effective_abilities": ["clients:view", "clients:edit", "projects:view", "projects:edit", "jobs:view", "jobs:edit"],
  "writable_features": ["clients", "projects", "jobs"]
}

Field	What it tells you
`granted_abilities`	What the key was made with
`effective_abilities`	What the key can do now. If an administrator changed the account's role, this list is shorter
`assigns_project_numbers`	`true` when your projects keep the numbers you send
`adds_staff_accounts`	`true` when the key can make staff accounts

The address to call

Use the Endpoint from Settings › API keys. A workspace with its own web address shows that address, and the main address works too, because the key names the workspace.

Keep the key safe

Keep the key on a server. Never send it to a web browser or a mobile app.
Do not write the key in logs.
Use one key for each system, so you can stop one system without stopping the others.
If a key is lost, click Rotate key in Settings › API keys.

When the key is refused

Status	Why	What to do
`401`	No key, an unknown key, or a key that was rotated or removed	Check the header. Make a new key if you need one
`403`	The integration is disabled, or the account it acts as cannot do this	Check `whoami`. Ask an administrator to change the account's role