Warrant Tokens

FGA is a distributed service deployed to multiple cloud regions. All traffic to the FGA API flows through a single endpoint (api.workos.com/fga). To ensure reliability, data is replicated to multiple regions behind the scenes. To maximize performance, FGA is an eventually consistent service by default.

In order to balance performance and consistency, FGA supports a bounded staleness protocol similar to Google Zanzibar’s Zookie protocol. This allows client applications to specify when they prefer the fastest results (to minimize latency added by authorization checks) and when they prefer immediately consistent results (to ensure recent changes to permissions are reflected for a particular check or query).

FGA generates an opaque token (known as a Warrant Token) for all warrant write operations (i.e. creating or deleting warrants). Each Warrant Token uniquely identifies a warrant write operation. All warrant write operations return a Warrant Token in the response body.

{
  "warrant_token": "MjM0fDM0MzQyM3wyMTM0MzM0MzY0NQ=="
}

Unlike traditional eventually-consistent distributed systems, FGA allows clients to specify their desired consistency level via Warrant Tokens. Clients can pass a previously generated Warrant Token via the Warrant-Token header on check, query, and list warrants requests to instruct the server to process the request using data no older than the write operation identified by the specified Warrant Token. This allows clients to ensure that a particular check, query, or list warrants request has the data necessary to give the most up-to-date result as dictated by the application’s authorization requirements.

In some cases, a client may need an up-to-date result but may not have an accompanying Warrant Token to use for the request. In this scenario, the client can pass the special value latest in the Warrant-Token header to instruct FGA to use the most up-to-date data:

'Warrant-Token: latest'

Note that using the latest token effectively instructs FGA to bypass all caches in favor of hitting the database for the most up-to-date result. Therefore, it can incur additional performance overhead, so it’s recommended to only use latest sparingly. Instead, opt to use server-provided Warrant Tokens or no token at all (the default consistency) to maximize performance in most cases.

In practice, clients can store Warrant Tokens in their system on a per-subject basis, passing in the stored token to each read request for that subject to achieve optimal performance. For example, if creating a new warrant (e.g. user:x is an editor of report:y) generates a Warrant Token with value 45f87sdf=, the client can store that token their db along for subject user:x. Subsequent checks or queries for user:x can then include that stored Warrant Token for the optimal balance of performance and consistency.

Passing a Warrant Token on check, query, and list warrants requests is optional. If a Warrant Token is not provided, FGA uses a default staleness window to fulfill check and query requests. This window is cache-optimized and is the recommended approach for the 90-95% of read requests that can tolerate short periods (on the order of seconds) of inconsistent results.