An integration designed
for mutual trust.

Joining the network

The design below is a proposal for technical discussion. Final participation criteria, agreements, environments and procedures will be defined before any operation begins.

1. Identification and alignment

   Validate the institution and its representatives, discuss the intended use and formalize responsibilities. The interest form does not perform this validation.

2. Security setup

   Exchange public certificates and certificate chains through an authenticated channel, register fixed outbound IP addresses and provision credentials with limited permissions.

3. Validation before production

   Validate authentication, authorization, the event contract and update procedures using synthetic data in a separate environment.

Layered security

Mandatory mTLS

The client and server validate each other’s certificates. Only public certificates and trust chains are exchanged. Private keys remain under their owner’s control and must never be submitted through the form or shared with Bastião.

Authorized IP addresses

Access depends on an allowlist of the institution’s fixed outbound IP addresses. Broad address ranges should not be allowed. Address changes require validation and an update in advance.

OAuth2 Client Credentials

A Bearer token identifies the integration and limits its operations. The proposed scopes are events:write for registration and events:read for queries. OAuth2 complements mTLS and the IP allowlist.

The proposal should include certificate and credential expiration, rotation and revocation, as well as audit trails and incident response.

Register an event

Illustrative example of a record with status under_review. The event reports an indication under review; it does not establish confirmed fraud.

curl --request POST 'https://api.bastiao.example/v1/events' \
  --cert "$CLIENT_CERT_PATH" \
  --key "$CLIENT_KEY_PATH" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": {"cnpj": "00000000000000"},
    "category": "suspected_identity_fraud",
    "status": "under_review",
    "occurred_at": "2026-01-15T12:00:00Z",
    "reference": "synthetic-event-001"
  }'

All data is synthetic. The CNPJ is a placeholder and must not be used as a valid registration number. The .example domain is not an operational endpoint. The variables point to local credentials and files; never include private keys in payloads.

{
  "id": "evt_synthetic_001",
  "status": "under_review",
  "created_at": "2026-01-15T12:01:00Z"
}

Query events

The proposed query returns signals accessible to the authenticated institution, according to purpose and authorization. The identity of the reporting party is not included in the proposed public response.

curl 'https://api.bastiao.example/v1/events?cnpj=00000000000000' \
  --cert "$CLIENT_CERT_PATH" \
  --key "$CLIENT_KEY_PATH" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "events": [{
    "id": "evt_synthetic_001",
    "category": "suspected_identity_fraud",
    "status": "under_review",
    "occurred_at": "2026-01-15T12:00:00Z"
  }]
}

The examples do not include real data, tokens or information identifying reporting parties. Pagination, usage limits and error handling will be defined in the final contract.

Records need context

The proposed model distinguishes events under review (under_review), confirmed after assessment (confirmed) and dismissed (dismissed). Criteria, permissions for status transitions, corrections and retention periods still depend on governance decisions.

The information should support the institution’s analysis, with quality controls and mechanisms for challenging records. Participation and each instance of data processing depend on an assessment of the applicable regulatory obligations and legal bases.