Skip to content
Authrim

List data retention categories.

GET
/api/admin/data-retention/categories
Code sample: Shell / cURL 
curl --request GET \
  --url https://auth.example.com/api/admin/data-retention/categories \
  --header 'Authorization: Bearer <token>'

Returns how long each kind of tenant data is kept, read from what actually decides it (the audit profile, a logging destination or the tenant PII config for audit logs, the Settings API for Check API decisions, diagnostic logs, sessions and tokens, the lookup directory policy, and the fixed retention of deleted users’ tombstones), where an admin changes it, and what removes the data (a scheduled retention task, expiry, or nothing because it is not stored). Answers 503 when any of these cannot be read.

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Data retention category list response.

Media type application/json
object
tenant_id
required
string
categories
required
Array<object>
object
id
required
string
Allowed values: audit_events audit_pii check_api_audit user_tombstones compliance_reports lookup_directory diagnostic_logs sessions refresh_tokens authorization_codes access_tokens
retention
required
object
value
required
number
> 0
unit
required
string
Allowed values: days seconds
key
additional properties
source
required

What decides the retention. setting (with category, key and level), session_settings (with keys), audit (with from: delivery_plan, audit_profile or pii_config), lookup_policy, or default (each record may have its own, set when it is made).

object
kind
required
string
Allowed values: setting session_settings audit lookup_policy default
category
string
key
string
level
string
Allowed values: tenant platform
keys
Array<string>
from
string
Allowed values: delivery_plan audit_profile pii_config
edit
required

Where an admin changes it: settings (Settings API category, key and level), session_settings, audit_pii_config, audit_profile, audit_routing_rules, lookup_directory (this API), or none.

object
kind
required
string
Allowed values: settings session_settings audit_pii_config audit_profile audit_routing_rules lookup_directory none
category
string
key
string
level
string
Allowed values: tenant platform
deletion
required

What removes the data: a scheduled_task (with its state and this tenant’s last run), expiry where it is kept, not_stored, or not_deleted (nothing removes it yet: the lookup directory, whose policy is projected to Control without a purge acting on it, and expired refresh token families, kept until rotated or revoked).

object
kind
required
string
Allowed values: scheduled_task expiry not_stored not_deleted
reason
string
Allowed values: lookup_purge_not_available expired_refresh_families_kept
task
string
enabled
boolean
disabled_reason
string | null
status
string
last_started_at
integer | null
last_completed_at
integer | null
last_error_code
string | null
next_run_at
integer | null
tenant_last_run

When the task last ran for this tenant. A run covers only some tenants (and, for diagnostic logs, one page of objects each; a tenant is recorded once all its objects were scanned), so the task’s own last run says nothing about this one.

object
at
required
integer
outcome
required
string
Allowed values: cleaned archive_only not_supported archive_copy_failed failed
projection
string
Allowed values: current pending
varies
required
string | null
Allowed values: by_route by_app by_sign_in_method by_request
cap

A limit below the setting that applies instead (the tenant profile’s token lifetime).

object
kind
required
string
Allowed values: tenant_profile
seconds
required
integer
counts
required
object
total
required
integer
expired
required
integer
extension

For sessions: an active session can be extended by per_refresh_seconds at a time; absolute_limit_seconds null means nothing bounds how long it may last in all.

object
per_refresh_seconds
required
integer
absolute_limit_seconds
required
integer | null
breakdown
Array<object>
object
key
required
string
seconds
required
integer
fixed

A lifetime fixed in code for this sign-in path (key names the path).

boolean
archive

Audit logs only: a copy also goes to an archive (R2). The deletion covers the primary store only; Authrim deletes nothing from the archive (an R2 lifecycle rule set outside Authrim may).

object
deletion
required
string
Allowed values: not_deleted
key
additional properties
key
additional properties
Example 
{
  "categories": [
    {
      "id": "audit_events",
      "retention": {
        "unit": "days"
      },
      "source": {
        "kind": "setting",
        "level": "tenant",
        "from": "delivery_plan"
      },
      "edit": {
        "kind": "settings",
        "level": "tenant"
      },
      "deletion": {
        "kind": "scheduled_task",
        "reason": "lookup_purge_not_available",
        "tenant_last_run": {
          "outcome": "cleaned"
        },
        "projection": "current"
      },
      "varies": "by_route",
      "cap": {
        "kind": "tenant_profile"
      },
      "archive": {
        "deletion": "not_deleted"
      }
    }
  ]
}

401

Section titled “401 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

403

Section titled “403 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Section titled “503 ”

What decides a retention cannot be read, so the values in effect are unknown.