Skip to main content

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:

GroupReach
memberReads their organization's data. Discover, exports, AS reports, sensors, own keys.
managerThe above, plus their organization's users, invites and its own detail page.
adminEverything, 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/summary
  • GET /api/public/map
  • GET /api/public/highlights
  • GET /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.