Features of the Wasabi Account Control API

Setup, Limits, and Policies

In order to use the Wasabi Account Control API, you must contact a representative from Wasabi to request access to the Wasabi Account Control API program. To be eligible for access to the API, you must:

• Have an established Wasabi account (hereafter referred to as a Control Account) that is tied to a payment method (that is, no longer in a trial period), such as a credit card or manual invoicing (if approved by your Wasabi Sales Representative)
• Meet any requirements as established by your Wasabi Sales Representative

It is important to note that while using the Wasabi Account Control API, you may not delete the Control Account. Transferring sub-accounts between different Control Accounts will not be supported. Your Wasabi Sales Representative will work with you to determine what limits will be applied to your Wasabi Account Control API participation, in particular:

• Maximum number of sub-accounts you will be allowed to create
• The default and maximum length of sub-account trial period
• The default and maximum trial period storage quota (in GB)

Emails

Wasabi typically sends Wasabi branded emails during the lifetime of an account, such as:

• A warning email when an account is nearing trial storage quota limit
• An email when a trial storage quota limit is surpassed and the account can no longer upload new objects
• Warning emails when an account is reaching the end of a trial period
• Notifications when account trials have expired (and at various points during the “offboarding” process until the account is deleted)

All emails are Wasabi branded and there is no option to co-brand or white label emails for API developers at this time. Therefore, as a user of the Wasabi Account Control API, you (Control Account holder) will receive notification emails on behalf of any sub-accounts. The body of the email will sufficiently indicate which subaccount on which the email notification is occurring.

Since Wasabi does not send notification emails to end users, Wasabi Control Account holders will be required to adequately notify end users of the above conditions. There is enough information in the Wasabi Account Control API to determine when the above thresholds are reached to properly communicate via your own user interface (UI) or email notification system.

Billing 

Billing occurs through your main Wasabi account (control account) and includes storage consumption of your sub-accounts. You will receive one bill for your Wasabi account and all your sub-accounts. Sub-accounts are not billed individually.

To determine the daily storage and data transfer amount associated with a sub-account across all buckets, see GET Utilizations for a Sub-Account.

All sub-accounts will be considered within the same billing scope of the Control Account, namely:

• Sub-accounts will be invoiced on the same periodicity as the Control Account.
• Sub-accounts, once out of trial, will be subject to the same minimums applied to all Wasabi accounts (for example, a 1 TB minimum storage charge).
• Sub-account invoices will be “rolled-up” into a single control invoice that is charged to the Control Account.
• Sub-accounts will follow any restrictions that are incurred by the billing status of the control account invoice. For example, object uploads will be disallowed once the control account invoice remains unpaid past a grace period.
• Trial sub-accounts will be automatically converted to paying accounts at the end of the sub-account trial period. It is possible (via this API) to extend a sub-account trial period, but there will be a maximum allowed trial duration that will be set by a Wasabi Sales Representative.
• At this point in time, once a trial sub-account converts to a paying account, it is not possible to put the sub-account back into trial. Therefore, it is the responsibility of the user of the Wasabi Account Control API to either:
  • Delete an unwanted trial sub-account before the trial period ends, or
  • Extend the trial period for the sub-account before the auto-conversion happens.

Authentication and Security

For security reasons, the Wasabi Account Control API caller must use HTTPS, as any non-HTTPS calls will be redirected to HTTPS endpoints.

Authentication of Wasabi Account Control API calls will be through the Authorization HTTP header. The caller must use the secret API key provided by Wasabi as the Authorization header value.

The user of the Wasabi Account Control API must keep the API key safe and protected. It is only to be used in trusted server-to-server communications and MUST NOT be put in any untrusted environments (such as browser-side JavaScript) or otherwise exposed to users or personnel that are not authorized to use that key.

If the security of an API key has been breached, it is the Wasabi Control Account holder’s responsibility to immediately contact Wasabi and have the old API key invalidated and a new API key generated.

The Wasabi Account Control API key will support rolling-key management where two sets of API keys are supported for an overlapping time period. Callers into the API can use either keys when making calls into the API. This allows for the expiration of one key while the other key remains valid during a transition period.

Test Environments

Wasabi will have a test environment for the Wasabi Account Control API available for development and testing purposes. The test environment will have API keys generated that are distinct from the live API keys.

The test environment, while generally stable, will not offer the same Service Level and Quality of Service as the Wasabi production environment. Therefore, users of the Wasabi Account Control API should expect some service disruptions of the test environment from time to time.

Rate Limiting

For security and performance reasons, the Wasabi Account Control API will rate limit the number of requests on a per Wasabi Control Account holder basis against the API methods listed below. These limits are currently:

• 1000 GET operations/min
• 100 PUT operations/min
• 100 POST operations/min
• 10 DELETE operations/min

Any call rates that exceed these limits will be responded with a standard “HTTP 429 Too Many Requests” response.

Utilization Metrics

Wasabi calculates usage metrics once per day at both a per-bucket and per-account level. These records are stored indefinitely in our systems and can be retrieved on demand. The metrics captured are:

"NumBillableObjects": 1,
"NumBillableDeletedObjects": 1,
"RawStorageSizeBytes": 1000000000,
"PaddedStorageSizeBytes": 1000000000,
"MetadataStorageSizeBytes": 87,
"DeletedStorageSizeBytes": 1000000000,
"OrphanedStorageSizeBytes": 0,
"MinStorageChargeBytes": 106374182313,
"NumAPICalls": 18,
"UploadBytes": 89349,
"DownloadBytes": 36784,
"StorageWroteBytes": 62325,
"StorageReadBytes": 0,
"NumGETCalls": 0,
"NumPUTCalls": 2,
"NumDELETECalls": 0,
"NumLISTCalls": 3,
"NumHEADCalls": 0,
"DeleteBytes": 0

• NumBillableObjects — The number of objects that are active (that is, not deleted) associated in the account/bucket as of midnight UTC at the time the calculation was made. This number is the total objects under storage and NOT new objects uploaded that day.
• NumBillableDeletedObjects — The number of objects that have been deleted, but — due to any minimum object lifetime requirements (typically 90 days) associated with the API developer’s billing plan — these objects are still calculated as part of the API developer’s monthly invoice and will be charged at the same rate as non-deleted objects. This number is the total deleted objects under storage and NOT new objects deleted that day.
• RawStorageSizeBytes — The number of bytes for all non-deleted objects in the account/bucket. This number is the total objects bytes under storage and NOT new objects uploaded that day.
• PaddedStorageSizeBytes — The number of bytes for all non-deleted objects in the account/bucket but with the minimum object size restriction enforced, based on the API developer’s billing plan (typically, minimum 4k object size). If you are working with objects all larger than 4k, then PaddedStorageSizeBytes will be the same as RawStorageSizeBytes. This number is the total objects bytes under storage and NOT new objects uploaded that day.
• MetadataStorageSizeBytes — The number of bytes associated with any metadata about the object that is stored in our databases. This number is normally a very small percentage of total storage and will likely be sub-penny in terms of billable amounts.
• DeletedStorageSizeBytes — The number of padded bytes for all deleted objects in the account/bucket. This number is the total objects bytes under storage and NOT new objects uploaded that day.
• NumAPICalls, UploadBytes, DownloadBytes, StorageWroteBytes, and StorageReadBytes — API activity related and reflect activity done between the specified time period on that day. That is to say, they are not cumulative across days, like storage metrics are.
• MinStorageChargeBytes — The number of bytes that a user should be charged because they are under the 1 TB minimum storage requirement.
• DeleteBytes — The sum of the number of all deleted bytes per account/bucket over the day. This is used to track general delete activity and is not used for any billable events.

Converting Metrics to Charges

The Wasabi Account Control API provides for retrieving sub-invoices for the sub-accounts. Sub-invoices are generated at the same time the control account invoice is computed (every 30 days) and accounts for all of the business rules outlined above (minimum object lifetime, minimum object size, minimum storage requirements, etc.). Therefore it is easiest for API developers to simply use this feature when creating chargeable events for the API developer’s customers.

However, if API developers wish to implement their own billing mechanism, the following indicates how to compute costs on a per-account basis:

Active Storage Charges

SUM-OVER-BILLING-PERIOD( MAX( ( ( PaddedStorageSizeBytes + MetadataStorageSizeBytes ) / POWER(1024, 3) ), 1024) * ( {partner-rate-per-TB-per-Month-with-Wasabi} / 30 / 1024) )

Deleted Storage Charges

SUM-OVER-BILLING-PERIOD( ( DeletedStorageSizeBytes / POWER(1024, 3) ) * ( {partner-rate-per-TB-per-Month-with-Wasabi} / 30 / 1024) )

Egress Charges

SUM-OVER-BILLING-PERIOD( DownloadBytes * {partner-rate-per-GB-egress} )

The MAX(..., 1024) in the Active Storage Charge is to reflect the minimum required storage business logic (in this case, 1 TB = 1024 GB). A future version of this API will include an additional metric in the Utilization to better reflect the minimum storage requirements.

To reiterate, the algorithms above will not be needed by API developers if they use the existing sub-invoice API endpoints described in the Invoices section. We highly recommend using the existing endpoints so as to not have to duplicate business logic in the API developer client code.