Billing, caching, and rate limiting

With Authress, you only ever pay for what you actually use. Unlike other providers, we won’t charge you the full month for users who only logged into your app once. The downside of this is a small bit of complexity when thinking about the API. Not every API route incurs charges. Some routes are rate limited. Some routes may be cached.

API route overview

Below is a high level overview of routes and their respective billing, caching, and rate limiting strategies.

In general, only routes marked as “billable” count towards your API call count. All routes that are cached include a Cache-Control header in their response.

Some routes aren’t intended to be utilized in bulk and are therefore restricted in terms of call frequency. When a rate limit is triggered for such route, it returns the status code 429. There are 4 tiers of rate limiting in Authress:

• Tier 1: 1 call per minute - these routes are expected to be used from Authress UIs only
• Tier 2: 1 call per second - these are administrative actions and should not be done transactionally
• Tier 3: 100s per second - meant for transactional but infrequent usage
• Tier 4: Unlimited - built for full parity with the resource application service

Creating and updating resources

These routes tend to be free. Because they aren’t REST-safe operations (PUT, POST, PATCH, DELETE), there is no caching.

Route	Billable	Rate Limiting
/v1/users/{userId}/tokens	$	Tier 3
/v1/users/{userId}/tokens/{tokenId}	$	Tier 3
/v1/resources/{resourceUri}		Tier 2
/v1/records/{recordId}		Tier 3
/v1/roles/{roleId}		Tier 2
/v1/claims		Tier 3
/v1/clients/{clientId}		Tier 2
/v1/clients/{clientId}/access-keys/{keyId}		Tier 3

Getting resources

Safe and idempotent operations may be cached. Caching is always bound to the token lifetime ceiling to prevent account resource takeovers and it can never be longer.

Route	Billable	Rate Limiting	Caching
/v1/users/{userId}/resources	$	Tier 4	30s
/v1/users/{userId}/resources/{resourceUri}/permissions	$	Tier 4	60s
/v1/users/{userId}/resources/{resourceUri}/permissions/{permission}	$	Tier 4	2XX - 24hr, 4XX - 60 s
/v1/users/{userId}/resources/{resourceUri}/roles	$	Tier 4	1s
/v1/resources		Tier 1	600s
/v1/resources/{resourceUri}		Tier 2	-
/v1/resources/{resourceUri}/users	$	Tier 3	5s
/v1/records		Tier 1	120s
/v1/records/{recordId}		Tier 2	1s
/v1/roles		Tier 1	-
/v1/roles/{roleId}		Tier 2	-
/v1/clients		Tier 2	30s
/v1/clients/{clientId}		Tier 2	5s

Authentication routes

These routes are utilized by the Authress Login SDK and most of them are billable. They operate across regions and are highly reliable and scalable.

Route	Billable	Rate Limiting
/authentication	$	Tier 4
/authentication	$	Tier 4
/.well-known/openid-configuration		Tier 3

Few more words about caching

Caching is always a tradeoff. On one hand, you want your data to be as fresh as possible, on the other hand, you also want your functions to return as fast as possible. Usually you can’t have both. Cache times in Authress are carefully tuned with this tradeoff in mind. Because of that, you don’t need to implement the caching yourself in most cases.

Caching is difficult to get right and often means you need to pull in additional frameworks into your code. Fine tuning the balance between performance and data freshness takes time and experience. In case of User-Agent integrations (for example, an application UI running in your user’s browser), it is even more crucial, as the User-Agent is rarely under your control and yet demands fast response times. This is why we’ve opted for caching on the Authress side in many cases.

It doesn’t mean you can’t cache returned values for longer - if you’re making a lot of the same, low variability permission checks, you may want to build a cache on top of Authress to limit your costs. It is not strictly necessary though.

If you find yourself wishing for shorter cache times and are willing to sacrifice your client service performance, feel free to let us know.