Authentication
Every request outside the public routes carries an API key as a bearer token:
curl -H "Authorization: Bearer $AIDE_KEY" https://gcaaide.org/api/metrics
The key is the session
Signing in exchanges an email and password for an API key, and that key is the session. There is no cookie and no separate session store, so the token a sensor uses and the token the browser holds are the same kind of object.
curl -X POST https://gcaaide.org/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"login": {"email": "you@example.org", "password": "..."}}'
{ "key": { "id": "...", "key": "ba7378fb-034b-40b1-b37f-edb8476bf8e7", "autoGenerated": true } }
Two consequences worth knowing:
- Signing out revokes the key. It stops authenticating immediately, including a request already in flight.
- A key created by signing in is marked
autoGenerated. Revoking it signs that session out. Keys you create yourself on the API Keys page are not, and are what a sensor or a script should use.
Keys are stored hashed
Only hex(sha256(key)) is stored. The plaintext exists between minting and the response that carries
it, and no endpoint can return it afterwards, deliberately: not the list endpoint, not the single-key
endpoint, not an admin one. Losing a key means creating another.
A key can be revoked or deleted. Prefer revoking: the row stays, so the record of when it was last used survives.
Groups
Three groups, and what a group may do is decided entirely by which routes accept it:
| Group | Reach |
|---|---|
member | Reads their organization's data. Discover, exports, AS reports, sensors, own keys. |
manager | The above, plus their organization's users, invites and its own detail page. |
admin | Everything, including hit submission, every organization, and the IPI pipeline. |
There is no group table, no permission table, and no screen for editing either. Reading the route registrations tells you the whole authorization story.
A key inherits its owner's group. AIDE allowed a key to hold a different role from its user; that was a privilege-escalation surface and is not reproduced.
What an organization may see
Group decides which endpoints answer. The organization's filter mode decides what the data contains, and it is applied in the logic layer on every read rather than trusted from the request.
The visible effect on the API: an organization without IP access has no clientIP or hostIP in
/discover/fields at all, rather than a field that is offered and then refused. A clause naming one
is a 403 that says which field and why.
Password reset
curl -X POST https://gcaaide.org/api/auth/reset-password \
-H 'Content-Type: application/json' -d '{"email": "you@example.org"}'
The response is the same whether or not the address has an account. Telling an anonymous caller which addresses exist would make this an account enumeration oracle.
Public routes
Four routes need no key, and are the only ones registered without a security scope:
GET /api/public/summaryGET /api/public/mapGET /api/public/highlightsGET /api/ip
The first three are the landing page. GET /api/ip reports how many times the caller's own
address hit the honeypots in a given month; it takes a month and a year and no address, which is
what stops it becoming a lookup of anyone else's.