Scenario
Northstar Event API is a fictional HTTPS API that accepts security-event records. The sample begins with the smallest useful path from credentials to an accepted request, then stays with the developer long enough to address field meaning, failure handling, and safe retry behavior.
What This Sample Demonstrates
This sample demonstrates task-first developer onboarding, authentication, HTTP and JSON, request validation, actionable error handling, and a clear distinction between required and optional metadata. It also shows the difference between documenting a response code and helping a developer decide what that response means for the integration.
Quickstart: Send Your First Event
Before You Begin
Prerequisites
- A POSIX-compatible shell, such as Bash or Zsh, with
curlinstalled. - The Northstar base URL for the environment you are testing.
- HTTPS access from your environment to
api.example.invalid. - A unique source event ID that has not been submitted before.
- A valid RFC 3339 UTC timestamp for the event.
- A way to confirm that the processed event reached the receiving application.
Required Permissions
- The token must have
events:writepermission to submit an event. - To check processing status through the API, the token must also have
events:readpermission. If you do not have that permission, arrange for an authorized operator to verify the event in the receiving application.
You do not need administrative access to the Northstar service for this procedure. Do not request broader permissions solely to complete the quickstart.
Treat the token as a secret. Do not place it in source control, screenshots, tickets, or readable shell history.
1. Set the Connection Values
Open a terminal in your approved development or test environment. Set the base URL for the environment you are testing. Then enter the token without placing its value in the command or shell history.
export NORTHSTAR_BASE_URL="https://api.example.invalid"
read -rsp "Northstar token: " NORTHSTAR_TOKEN
echo
export NORTHSTAR_TOKEN
Confirm that both variables are set without printing the token.
test -n "${NORTHSTAR_BASE_URL}" && echo "Base URL is set"
test -n "${NORTHSTAR_TOKEN}" && echo "Token is set"
Look for both confirmation messages. If either command returns no message, set that value again before continuing.
2. Submit an Event
Send one event with a unique event_id. Replace the example values with a test event that is safe to send to your environment. The --include option displays the HTTP status and response headers with the response body.
curl --silent --show-error --include --request POST \
--url "${NORTHSTAR_BASE_URL}/v1/events" \
--header "Authorization: Bearer ${NORTHSTAR_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"event_id": "fw-20260817-000184",
"occurred_at": "2026-08-17T12:41:09Z",
"source": "edge-firewall-03",
"event_type": "authentication.failure",
"severity": "medium",
"message": "Repeated failed administrative login attempts"
}'
3. Confirm Acceptance
A successful request returns 202 Accepted and a response body like the following:
{
"event_id": "fw-20260817-000184",
"ingest_status": "accepted",
"request_id": "req_71c8d4b9",
"accepted_at": "2026-08-17T12:41:10Z"
}
Look for:
- An HTTP status of
202 Accepted. - The same
event_idyou submitted. - An
ingest_statusofaccepted. - A
request_idyou can use to trace and verify processing. - An
accepted_attimestamp.
Record the request_id. Acceptance means that Northstar received and queued the event; it does not prove that downstream processing completed.
4. Verify Processing
If your token has events:read permission, replace the example request ID with the value returned in Step 3 and check its status.
curl --silent --show-error --include --request GET \
--url "${NORTHSTAR_BASE_URL}/v1/requests/req_71c8d4b9" \
--header "Authorization: Bearer ${NORTHSTAR_TOKEN}"
A processed event returns 200 OK and a response like the following:
{
"request_id": "req_71c8d4b9",
"event_id": "fw-20260817-000184",
"ingest_status": "processed",
"processed_at": "2026-08-17T12:41:11Z"
}
Look for:
- The same
request_idandevent_idreturned when you submitted the event. - An
ingest_statusofprocessed. - A processing timestamp later than the event's acceptance time.
Finally, confirm that the event appears in the receiving application. If the request remains accepted or pending, honor any Retry-After header and retry only within your integration's approved limit. If it reports failed, record the request ID and error details before changing the payload.
Request Fields
| Field | Required? | Purpose |
|---|---|---|
event_id |
Yes | Stable source identifier that supports duplicate detection. |
occurred_at |
Yes | Original event time in RFC 3339 UTC. |
source |
Yes | System or component that produced the event. |
event_type |
Yes | Normalized category used for routing and analysis. |
severity |
No | Source-assigned severity. |
message |
No | Short description for an operator. |
Common Errors
400 Bad Request
Correct the named field. Do not retry an unchanged invalid payload.
401 Unauthorized
Check the Bearer scheme, token status, and environment variable without printing the token.
403 Forbidden
Use a credential with events:write permission.
409 Conflict
Determine whether the source reused an ID. Do not generate a random replacement before investigating.
429 Too Many Requests
Honor Retry-After and use bounded retries with backoff.
Verify Before Integrating
Before adding the API call to an application or automated workflow, verify the complete behavior in an approved test environment:
- Submit a valid event and confirm both
202 Acceptedand the finalprocessedstatus. - Confirm that the event appears in the receiving application with the expected ID, timestamp, source, type, and message.
- Submit a payload that omits one required field. Confirm that the API returns
400 Bad Request, identifies the missing field, and does not ingest the event. - Resubmit a previously accepted
event_id. Confirm that the API returns409 Conflictand that the original event remains unchanged. - Verify that application logs retain the
request_idbut never record the token.
Do not deliberately trigger rate limiting or use expired credentials in a shared environment unless that test has been approved.
Integration Checklist
- Keep tokens out of code and logs.
- Send UTC timestamps and stable source event IDs.
- Log the returned request ID.
- Distinguish validation failures from retryable failures.
- Verify final processing rather than treating
202 Acceptedas completion. - Test a success and representative
400and409error paths.
Why the Documentation Is Shaped This Way
The smallest successful path comes first because developers need a working request before they need a complete reference. Field detail and failure handling follow while the request is still familiar. Each error includes a corrective decision because a status code without a next step is only half a diagnostic.
The sample also preserves operational boundaries. It does not print secrets, treat every failure as retryable, or recommend replacing evidence with a random new identifier. Those choices are part of technical accuracy, not decorative safety language added after the procedure is written.
