Skip to main content

Facts

Often, when trying to express business or security objectives in policy, you find yourself wanting to reference some self-standing piece of truth when writing a rule.

When that piece of information is something about the authenticated user, such as "Fred is on the fraud team" or "Bob is a US Citizen" usually that should be captured as a capability. See Domain Identity for more information about capabilities. Often, however, there are pieces of information that don't fit well into that model, such as:

  • Which customers have opted in to a particular data usage pattern
  • Which teams are part of an org
  • Which users have access to a folder or project

These are best captured as facts. To do so, you first create a fact type which is a bit like a schema for the facts. A fact is just a tuple of named arguments. When you create a fact type, you are declaring what those arguments are, and optionally some documentation text for them:

import antimatter as am
amr = am.Session.from_api_key(domain_id="dm-xxxxxxxx", api_key="xxxxxxxxx")
# create a fact type with just one argument
amr.add_fact_type("customer_ml_opt_in",
    description="Stores customer opt-in for ML features",
    arguments={
        "customer": "the ID of the customer"
    }
)
# create a fact type with two arguments. In this example, users
# may have a team capability, and data is tagged with a project.
# This fact records which teams have been assigned which projects
amr.add_fact_type("team_is_assigned_project",
    description="Records which teams are responsible for which projects",
    arguments={
        "team": "the name of the team",
        "project": "the name of the project"
    }
)

Once you have created a fact type, you can add, list and remove facts within that type:

import antimatter as am
amr = am.Session.from_api_key(domain_id="dm-xxxxxxxx", api_key="xxxxxxxxx")

# Add some facts
amr.add_fact("customer_ml_opt_in", "customer_one")
amr.add_fact("customer_ml_opt_in", "customer_two")
amr.add_fact("tag_is_redacted_for_team", "customer_support", "tag.antimatter.io/ssn")
amr.add_fact("tag_is_redacted_for_team", "customer_support", "tag.antimatter.io/phone_number")

# remove a fact, using its arguments
amr.delete_fact("customer_ml_opt_in", "customer_two")

# list the facts for a type:
amr.list_facts("customer_ml_opt_in")

Which returns:

[
 {'id': 'ft-0rfxt4571l0b6cio',
  'name': 'customer_ml_opt_in',
  'arguments': ['customer_one']}
]

To remove a fact by ID

amr.delete_fact("customer_ml_opt_in", fact_id="ft-0rfxt4571l0b6cio")