Key management FAQs

Limit by key FAQs

What is "limit by key"?

Limit by key is a feature that allows you to set API usage limits per key to prevent overuse and manage costs.

Why would I need to limit API usage by key?

To protect system performance, limit or prevent runaway code, control internal team budgets, provide insight to OEM and downstream users, bill for chargebacks, etc.

How do I set limits on an API key?

Limits can be configured in the API dashboard by specifying lookup limits per key and per-second rate limits by key.

What types of limits can I set?

Currently, users can limit the total number of lookups per key and the per-second rate limits by key. Limits can be set for the life of that key or until that key is reset.

What's the difference between an embedded key and a secret key?

A secret key is private and intended for backend server-to-server communication, while an embedded key is public-facing and designed for client-side use, with restrictions such as IP or domain limits.

What type of keys can I set limits on?

You can set lookup and rate limits on both embedded and secret keys.

What happens if a key exceeds its allowed rate limit?

When a key reaches a rate limit, the limit clears automatically after the duration limit is met. Additionally, users can always increase or decrease a rate limit on a key in the Account Dashboard.

What happens if a key exceeds its allowed lookup limit?

When a key reaches its lookup limit, all requests are blocked until you reset the counter, increase the limit, or remove it. If you need more lookups in your plan, contact your account executive.

What if my subscription already has a rate limit? How does a key rate limit interact with it?

A subscription rate limit always takes precedence over a key-based rate limit.
For example, if your subscription allows 25,000 lookups per second, and you configure a key rate limit of 30,000 lookups per second, the subscription limit will be enforced first. Because of this, the key limit would never be reached.
Key limits are most useful when you want to restrict usage for specific keys below your overall subscription limit, such as limiting usage for a particular application, team, or integration.

Can I apply different limits to different keys?

Yes. Limits can be customized for each key based on usage needs.

Can I change or remove a limit after setting it?

Yes. Limits can be adjusted or removed anytime via the Smarty Account Dashboard by the account owner or API key editor.

What happens when an API key reaches its limit?

Requests will be denied (429 error), and the limit will be shut off until an account owner or API key editor logs in, the counter is reset, or the limit is removed or increased.

Can I set limits dynamically based on usage patterns?

Not currently. The system won't adjust dynamically, but we don't prevent you from changing your limits in any way, shape, or form. You could adjust as often as you'd like if you need dynamic control.

Is there a way to group API keys by project or team?

You can add labels to your keys, allowing you to better distinguish between teams or code areas that use that specific key.

How do "usage by key" and "limit by key" improve API security?

Tracking API usage by key helps identify unauthorized or excessive activity, while limiting usage by key prevents abuse. Together, they protect against potential security breaches, DDoS attacks, and unauthorized access.

Can I limit API access for specific keys?

Yes, you can configure lookup limits and rate limits for each key to help with forecasting, budgeting, and prevent overuse.

Will I receive alerts when a key is close to its limit?

Yes! All users and contacts on the account receive an email when a key reaches 90% of its usage limit as part of its overall subscription. Users also receive an email when all lookups have been exhausted. In addition, key management lookup limits will trigger emails when a limit is added, when it's reached, and when it's been removed.

How can I monitor which keys are nearing their limits?

The usage by key and rate limit by key reports provide real-time tracking and historical reports to monitor usage. They're available in all Smarty yearly plans and are located in the "API Keys" section of the dashboard.

Can I temporarily increase a key's limit if needed?

Yes, account owners and API key editors can manually adjust limits to accommodate temporary spikes in usage.

Does limiting API usage by key affect billing?

Yes, it helps prevent unexpected overages, optimize API costs, and allocate budgets more effectively.

Can I track which keys are hitting their limits most often?

Yes, the rate limit key and usage by key reports let you identify which keys require limit adjustments.

Can I see which keys are using specific licenses?

Yes! The usage by key report includes license information, so you can see which keys are using which licenses.

Reports FAQs

How can I track my key management limits?

Users can download the "Usage by key" report to view their lookup usage or the "Rate limit by key" report to view rate limit events.

Why is tracking API usage by key important?

It helps monitor and manage API consumption per key, helping you optimize costs, detect anomalies, and allocate resources effectively.

Is usage by key included in my plan?

All annual subscriptions include key usage tracking. If you're on a monthly plan, contact us to see if a yearly plan would be a better fit.

How do I access reports via "Reports?"

1. Log in to your Smarty Account Dashboard and navigate to "Reports."
2. Locate the download button next to the report you would like to download.
3. Select all keys or specific keys that you'd like included in the report.
4. Determine the time frame you'd like to view: past 30 days, past 60 days, or a custom date range, and then export.

*Note: Data is only available from July 2, 2024, to the present.

How do I access reports via "API Keys?"

1. Log in to your Smarty Account Dashboard and navigate to "API Keys."
2. Locate the "Usage by key" button.
3. Select all keys or specific keys that you'd like included in the report.
4. Determine the time frame you'd like to view: past 30 days, past 60 days, or a custom date range, and then export.

*Note: Data is only available from July 2, 2024, to the present.

What information is provided in the "Usage by key" report?

• Security key
• Key name
• License
• Timestamp (by hour)
• Lookups used (per hour)

What information is provided in the "Rate limit by key" report?

• Security key
• Key name
• UTC Created
• UTC Expiration
• Status

Can I export reports for analysis?

Yes, your report can be downloaded in a CSV format from the "Reports" section on your Account Dashboard.

How often can I access my reports?

You can pull reports as often as you'd like. You can pull one report per day or hundreds (though we're not sure why you would…). It's up to you. Each report is pulled in 6-month increments.

Can I pull a single report that includes all my keys?

Yes! You can run a report for individual keys or a single report that includes all your keys, including embedded and secret.

How far back does the "Usage by key" data go back?

Usage data is available from July 2, 2024, to the present.

How frequently is data updated in reports?

Usage data is updated in real time.