Skip to main content

Audit logs

Some API operations are audited, including retrieving card secrets, recording a KYC attestation, blocking an account, and issuing a refund.

This page explains what that means in practice, and what it doesn’t mean.

The audit log is meant to be reviewed by a person investigating an event, under an identity that is subject to access control. That means it lives in Cockpit rather than behind an API credential your services can use.

Cockpit's audit log is part of the team and access-control work rather than the initial API release. If you need audit evidence for an assessment before then, your account contact can retrieve it.

This is intentional. If the audit log were available through the API, anything with an access token could read it, which defeats much of the point of having an access-controlled audit trail.

What is recorded​

There are two categories, and they exist for slightly different reasons.

Actions taken through the API​

ActionWhy it is recorded
Reveal card secretsA full card number was released. This is the most sensitive action on the platform
PIN set and PIN verifyRecords PIN changes and lockout history
KYC attestationsShows who asserted what and when — see re-verification
Cardholder record changesShows when PII changed and which credential made the change
Account block and unblockRecords when funds were made unavailable or available again
RefundsIncludes the reason you supplied
Card lifecycle actionsActivate, freeze, replace, and close

Each entry is tied to the credential that made the request.

This is why one client per deployment target is more than just good housekeeping. If you share one client across everything, the audit trail can tell you that an action happened without telling you which of your systems did it.

Actions taken in Cockpit​

Cockpit records more because a person can do things that an API credential can't:

  • Reads of PII, not just writes: Looking at a cardholder’s details is itself recorded.
  • Card reveals: Each one requires step-up authentication and is tied to a named user.
  • Role and permission changes: These can change who has access to sensitive data and actions.
  • Support access by AletaPlanet staff: If our support team needs to access or act on your organization, that appears in your audit record as well as ours.

Check this during an evaluation rather than assuming it works this way. There’s a meaningful difference between a vendor where staff access is visible to you and one where you simply have to take their word for it.

The half you have to keep yourself​

Our audit record answers “what happened on the platform?” It can’t answer “who at your company caused it?”

From our side, every request from your backend comes from your backend.

The two sides are joined by Aleta-Request-Id, which is returned on every response, including successful ones.

For sensitive actions, make sure you record these on your side:

RecordFor
Which of your users triggered a card reveal, and the step-up resultAnswering “who saw this number?”
Which staff member or system submitted each KYC attestationWe record that your organization made the assertion; only you know who actually submitted it
The ticket or case reference behind support-initiated actionsConnecting an event to the reason it happened
The Aleta-Request-Id for all of the aboveJoining your records to ours

Immutability​

Audit entries are append-only. Nothing in the API or Cockpit can edit or delete an existing entry.

This also applies when something is superseded. For example, a new KYC attestation replaces the previous one for current-state purposes, but both attestations remain in the audit trail.

That’s what makes the trail useful, but it also means one thing is worth keeping in mind:

Anything you put in a free-text field is permanent.

The notes and reason fields are recorded exactly as provided. Don’t use them for speculation about a cardholder, or for information that belongs somewhere else.

Retention​

Retention periods are set per program and are covered in the security questionnaire provided under NDA rather than published here.

There are two things to keep in mind when planning your own retention:

  • Your retention obligation is separate from ours. Your regulator determines what you need to keep.
  • Set your retention floor based on the dispute window, not just operational needs. A cardholder can raise a dispute well after a purchase, and you may still need the supporting evidence. Scheme deadlines also apply.
Last updated on