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.
API route overview​
Below is a high level overview of routes and their respective billing, caching, and rate limiting strategies.
This is the official list of billable routes. Only routes marked as “billable” count towards your API call count. Routes not listed here are billable.
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 5 tiers of rate limiting in Authress:
| Tier | Rate | Expectation |
|---|---|---|
| Special Tier | 1 call per hour per resource | Infrequent usage expected, usually triggered by Infrastructure as Code or through a seldom end user action. API Key generation is a good example. Requests are rate limited based on resource. Each resource has its own rate limit. |
| Portal Tier | 1 call per minute | These routes are expected to be used from Authress Management Portal only, however there is some bandwidth supported for these calls outside of the Management Portal. |
| Tier 1 | 1 call per second | These are administrative actions and should not be done transactionally. The creation of applications or authentication identity connections. |
| Tier 2 | ~100 calls per second | Meant for transactional with lower frequency. Whereas authorization requests will be continuous and frequent a good example of a Tier 2 is a query to list resources that belong to a user. |
| Tier 3 | Unlimited | The firehose - built for full parity with your resource application service. Call it as often and as frequent as you need all the way up to your Authress account configured limit. The default limit for every Authress account is 1000 RPS, please contact our Support for a higher account rate limit. |
Creating and updating resources​
These routes tend to be free. Because they aren’t REST-safe operations (PUT, POST, PATCH, DELETE).
| Route | Billable | Rate Limiting |
|---|---|---|
/v1/users/{userId}/tokens | $ | Tier 2 |
/v1/users/{userId}/tokens/{tokenId} | $ | Tier 2 |
/v1/resources/{resourceUri} | Tier 1 | |
/v1/records/{recordId} | Tier 2 | |
/v1/roles/{roleId} | Tier 1 | |
/v1/claims | Tier 2 | |
/v1/clients/{clientId} | Tier 1 | |
/v1/clients/{clientId}/access-keys/ | Special Tier | |
/v1/clients/{clientId}/access-keys/{keyId} | Tier 2 |
Getting resources​
| Route | Billable | Rate Limiting |
|---|---|---|
/v1/users | $ | Tier 1 |
/v1/users/{userId} | $ | Tier 2 |
/v1/users/{userId}/resources | $ | Tier 3 |
/v1/users/{userId}/resources/{resourceUri}/permissions | $ | Tier 3 |
/v1/users/{userId}/resources/{resourceUri}/permissions/{permission} | $ | Tier 3 |
/v1/users/{userId}/resources/{resourceUri}/roles | $ | Tier 2 |
/v1/resources | Portal Tier | |
/v1/resources/{resourceUri} | Tier 1 | |
/v1/resources/{resourceUri}/users | $ | Tier 2 |
/v1/records | Portal Tier | |
/v1/records/{recordId} | Tier 2 | |
/v1/roles | Portal Tier | |
/v1/roles/{roleId} | Tier 1 | |
/v1/clients | Tier 1 | |
/v1/clients/{clientId} | Tier 1 | |
/v1/clients/{clientId}/.well-known/openid-configuration/✶ | $ | Tier 2 |
/v1/connections | Tier 1 | |
/v1/connections/{connectionId} | Tier 1 | |
/v1/applications | Special Tier | |
/v1/applications/{applicationId} | Special Tier |
Public key verification​
These routes may be utilized by Platform Extensions and Service Client authentication. These are highly cacheable and seldom change. They are billed to encourage the use of client side caching.
| Route | Billable | Rate Limiting |
|---|---|---|
/v1/clients/{clientId}/.well-known/openid-configuration/✶ | $ | Tier 3 |
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 |
|---|---|---|
/connections/{connectionId}/users/{userId}/credentials | $ | Tier 2 |
/authentication | $ | Tier 3 |
/authentication/✶ | $ | Tier 3 |
/authentication/oauth/tokens | $ | Tier 3 |
/session | $ | Tier 3 |
/.well-known/openid-configuration | Tier 2 |
Due to the security risks associated with storing user passwords, the password based connection costs and additional $0.011 per login request. All other authentication mechanisms are billed at the standard API rate associated with your account.
Administrative Routes​
These routes are exposed to make it easier to perform complex meta-management of your Authress account. In general they are billable. We recommend reaching out to us if you plan use them directly.
| Route | Billable | Rate Limiting |
|---|---|---|
/v1/accounts/{accountId}/usage | $ | Portal Tier |
Authress Service Level Agreement - SLA​
The 99.999 SLA applies to Tier 2 & 5 routes that are not List Queries. Query based routes, such as GET /groups or GET /records, all other tiers are part of the lower 99.99% SLA.
Response 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. Authress provides suggested cache times on responses so that they can be used for optional caching on the client side.
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 to provide cache recommendations 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.