Grunderna
- Bas-URL:
https://ipmanager.no/api/v1 - Alla förfrågningar och svar är JSON (
Content-Type: application/json). - Autentisering med API-nyckel i headern
Authorization: Bearer ipm_…. - Alla ändringar via API:et loggas i revisionsloggen, med nyckelns namn som utförare.
API-nycklar och behörigheter
Nycklar skapas under Automatisk identifiering och API av en administratör. Nyckeln visas bara en gång. Varje nyckel har en behörighet:
| Behörighet | Kan |
|---|---|
read | Läsa adresser, subnät och sökning (GET) |
write | Allt som read kan, plus skapa, ändra och ta bort |
agent | Bara skicka agentrapporter (POST /agent/report) |
Exempel
curl -H "Authorization: Bearer $IPM_TOKEN" https://ipmanager.no/api/v1/search?q=10.20.3Endpoints
| Metod | Sökväg | Beskrivning |
|---|---|---|
| GET | /addresses | Lista adresser. Parametrar: q, status, subnet, limit, offset |
| POST | /addresses | Skapa en adress |
| GET | /addresses/{id} | Hämta en adress |
| PATCH | /addresses/{id} | Ändra fält på en adress |
| DELETE | /addresses/{id} | Ta bort en adress |
| GET | /subnets | Lista subnät |
| POST | /subnets | Skapa ett subnät |
| GET | /subnets/{id} | Hämta ett subnät |
| PATCH | /subnets/{id} | Ändra ett subnät |
| DELETE | /subnets/{id} | Ta bort ett subnät (adresserna finns kvar) |
| GET | /subnets/{id}/next-free | Nästa lediga IPv4-adress i subnätet |
| GET | /search?q= | Samma sökning som i gränssnittet, inklusive filter |
| POST | /agent/report | Rapport från agent eller insamlare |
| GET | /agent/dns/targets?cidr= | Registrerade adresser med värdnamn som ska DNS-kontrolleras (behörighet agent eller read) |
| POST | /agent/dns/report | Resultat av DNS-kontroll från insamlaren |
| GET | /conflicts | Lista avvikelser |
| POST | /conflicts/{id} | Hantera en avvikelse (kvittera eller lös) |
Adressfält
| Fält | Typ | Kommentar |
|---|---|---|
ip | text | IPv4 eller IPv6. Obligatoriskt när adressen skapas |
status | text | used, free, reserved, dhcp, offline eller deprecated. Standard used |
hostname | text | Sparas med gemener |
mac | text | Alla vanliga skrivsätt, sparas som aa:bb:cc:dd:ee:ff |
device, device_type | text | Enhet och enhetstyp |
room, department, site, owner | text | Placering och ansvar |
description | text | Fritext |
tags | lista | Till exempel ["server", "produktion"] |
custom | objekt | Egna fält, till exempel {"rack": "A12"} |
subnet_id | uuid | Sätts automatiskt till det mest specifika subnätet |
source, last_seen_at | – | Källa (manual, import, agent, scan, api) och senast sedd |
created_at, updated_at | tid | ISO 8601 |
Exempel
Skapa en adress
curl -X POST https://ipmanager.no/api/v1/addresses \
-H "Authorization: Bearer $IPM_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"10.20.3.41","hostname":"pr-b215","status":"used","room":"B2.15","tags":["skrivare"]}'Ändra en adress
curl -X PATCH https://ipmanager.no/api/v1/addresses/{id} \
-H "Authorization: Bearer $IPM_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"deprecated","description":"Byts ut vecka 42"}'Skapa ett subnät
curl -X POST https://ipmanager.no/api/v1/subnets \
-H "Authorization: Bearer $IPM_TOKEN" \
-H "Content-Type: application/json" \
-d '{"cidr":"10.20.4.0/24","name":"Elever hus C","vlan":31,"gateway":"10.20.4.1"}'Nästa lediga IP
curl -H "Authorization: Bearer $IPM_TOKEN" \
https://ipmanager.no/api/v1/subnets/{id}/next-freeSök med filter
curl -G https://ipmanager.no/api/v1/search \
-H "Authorization: Bearer $IPM_TOKEN" \
--data-urlencode 'q=status:free in:10.20.0.0/16'Agentrapport
Agenter och insamlare använder POST /agent/report med en nyckel som har behörigheten agent. En agent rapporterar sina egna gränssnitt:
Från en agent
{
"hostname": "srv01",
"os": "Linux",
"interfaces": [
{ "name": "eth0", "ip": "10.0.0.5", "mac": "00:11:22:33:44:55" }
]
}Från en insamlare
{
"source": "scan",
"hosts": [
{ "ip": "10.0.0.7", "hostname": "printer-2", "mac": "aa:bb:cc:dd:ee:ff" }
]
}Svar
{ "created": 1, "updated": 0, "unchanged": 3, "limited": 0, "errors": [] }DNS-kontroll
Insamlaren hämtar först vad som ska kontrolleras och rapporterar sedan resultatet. Se automatisk identifiering.
Hämta adresser som ska kontrolleras
curl -G https://ipmanager.no/api/v1/agent/dns/targets \
-H "Authorization: Bearer $IPM_TOKEN" \
--data-urlencode 'cidr=10.20.0.0/16'
{ "suffix": "skola.local", "targets": [ { "ip": "10.20.0.11", "hostname": "fil01" } ] }Rapportera resultatet
POST /api/v1/agent/dns/report
{
"resolver": "10.20.0.2",
"results": [
{ "ip": "10.20.0.11", "ptr": ["fil01.skola.local"], "forward": ["10.20.0.11"], "forward_checked": true }
]
}
{ "checked": 1, "ok": 1, "problems": 0, "unknown": 0 }Avvikelser
GET /conflicts listar organisationens avvikelser, som dubblerad IP, fel eller flyttad MAC och DNS-avvikelser, med allvarlighetsgrad (critical, warning, info). POST /conflicts/{id} används för att kvittera eller lösa en avvikelse. Alla ändringar loggas i revisionsloggen.
Fel
Fel returneras med en HTTP-statuskod och ett JSON-objekt: {"error": "kod", "detail": "…"}.
| Status | Typiska koder | Betyder |
|---|---|---|
| 400 / 422 | invalid_ip, invalid_cidr, invalid_mac, invalid_status, invalid_vlan, gateway_outside | Ogiltiga data i förfrågan |
| 401 | unauthorized, invalid_token | Saknad eller ogiltig nyckel |
| 403 | insufficient_scope, forbidden, ip_limit_reached | Nyckeln saknar behörighet, eller adressgränsen är nådd |
| 404 | not_found | Finns inte i din organisation |
| 409 | duplicate_ip, duplicate_subnet | Adressen eller subnätet finns redan |