====== OpenFGA Check API ======

The **Check API** is the part that answers the core question:
**"Is this user allowed to do this thing?"** Your app sends a question, and
OpenFGA replies ''allowed: true'' or ''allowed: false''.

This is the piece your app calls the most. It uses the
[[security:authorization:openfga:authorization-model|authorization model]] (the rules)
and the [[security:authorization:openfga:relationship-tuples|relationship tuples]] (the data)
together to reach an answer.

===== Why it exists =====

Your app should not hold permission logic in its own code. Instead, before any
sensitive action, it asks OpenFGA. This keeps all rules in one place and gives a
fast, consistent yes/no everywhere.

===== What a Check asks =====

A Check question has the same three parts as a tuple, plus the store and model
it runs against.

^ Part ^ Meaning ^ Example ^
| **user** | who is asking | ''user:anne'' |
| **relation** | the action or link to test | ''viewer'' |
| **object** | the thing being accessed | ''document:budget'' |

In words: "Can Anne view the budget document?"

<code>
Check: user:anne  viewer  document:budget
</code>

===== What it returns =====

A simple boolean.

<code>
{ "allowed": true }
</code>

  * **true**: a valid path was found. Access granted.
  * **false**: no path was found. Access denied.

===== How a Check resolves =====

The model plus the tuples form a graph. A Check //walks// that graph.

  - Your app asks the question.
  - OpenFGA reads the model to learn what path would allow it.
  - OpenFGA walks the tuples, following direct grants and computed relations.
  - If the links connect, it returns ''true''. If not, ''false''.

Example: Anne is not a direct viewer, but she is an ''editor'', and the model says
''viewer'' includes ''editor''. The walk connects, so the answer is ''true''.

===== Contextual tuples =====

A Check can include **contextual tuples**: extra facts passed in for this one
question only. They are never stored. Use them for data you know at request time,
such as the user's current department.

===== Conditions (ABAC) =====

If the model uses conditions, the Check can pass **context** values (like time or
amount). OpenFGA evaluates the condition as part of the walk. The grant only
counts if the condition is true.

===== Consistency options =====

OpenFGA caches data for speed. A Check can ask for different consistency levels:

  * **Higher consistency**: always read the newest data. Safer, a little slower.
  * **Lower consistency**: allow cached data. Faster, may be slightly stale.

<note tip>
Right after you write a tuple, use a higher-consistency Check if the new grant
must take effect immediately.
</note>

===== Related queries =====

The Check API answers one yes/no question. OpenFGA has sibling queries for other
needs:

  * **BatchCheck**: many Check questions in one call.
  * **Expand**: show //why// access is granted (the full path).
  * **ListObjects**: "Which documents can this user read?"
  * **ListUsers**: "Who can access this document?"

===== How it fits =====

Input → Process → Output:

  * **Input**: your app sends ''(user, relation, object)'' with the store and model.
  * **Process**: OpenFGA walks the graph of rules and tuples.
  * **Output**: ''allowed: true'' or ''allowed: false''; your app allows or blocks the action.

===== See also =====

  * [[security:authorization:openfga:store|Store]]
  * [[security:authorization:openfga:authorization-model|Authorization model]]
  * [[security:authorization:openfga:relationship-tuples|Relationship tuples]]
  * [[https://openfga.dev/docs/interacting/relationship-queries|Relationship queries (Check, Expand, ListObjects)]]