Associations

Record that two addresses are observed to be operated together.

Always recorded as an assertion, whatever the body says: the state and the provenance are not parameters. An assertion changes nothing served about either address and cannot until a signature is checked, which is what keeps naming somebody else's addresses from being an attack. Authenticated, so that every record has an author who can be asked about it. An assertion nobody corroborates is retracted rather than kept.

post/v1/associations

Request

  • Base URL: https://api.fidren.net
  • URL: https://api.fidren.net/v1/associations
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

addressstring required
peer_addressstring required
chainstring
groundsstring required

What was observed. Not a statement about who anybody is; such a statement is not published at any confidence.

self_declaredboolean

Whether the caller is speaking about its own addresses. It changes the recorded provenance and nothing else: a self-declaration is inert until a signature arrives, exactly as a third-party assertion is.

Response

The recorded assertion.

public_idstring nullable required

The stable, opaque identifier for this association, and the one to store. Accepted wherever an association is addressed. Null only on a legacy row that predates this field.

idinteger required

Deprecated legacy identifier. It is a global sequence, so the difference between two of them discloses roughly how much other traffic Fidren handled in between; it is retained only because removing it would break existing clients. Use public_id. It is not carried into the next API namespace.

chainstring required
addressstring required
peer_addressstring required
provenance'SELF_DECLARED' | 'THIRD_PARTY' | 'PROVEN_CONTROL' | 'BOTH_PARTIES_SIGNED' required

How the record came to exist. It never substitutes for the ladder below: an assertion changes nothing served whoever made it.

status'ASSERTED' | 'CORROBORATED' | 'CONTESTED' | 'CORRECTED' | 'RETRACTED' required

The state decides whether an assessment ever sees the record. Only CORROBORATED reaches it. CORRECTED and RETRACTED are terminal.

confidence'LOW' | 'MEDIUM' | 'HIGH' required
association_versionstring required

The association rules in force when the row was written. It moves on its own schedule, so a revision that widens association is visible as a revision.

observed_atstring date-time required
corroborated_atstring date-time nullable required
resolved_atstring date-time nullable required
expires_atstring date-time nullable required

When an assertion that was never corroborated stops being left open and is retracted. Retraction stops future effect; it is not a finding that the record was wrong, and it deletes nothing.

notestring

Plain-language statement of what this write changed and what it did not. Present on the responses to POST /v1/associations and POST /v1/associations/{id}/corroborate; absent from GET /v1/associations/{id}, which reports the record and no action. Prose for a human — its wording may change; do not parse it.

Changes

No recorded changes to this operation across all 1 revision of this API.