Offering an API to Your Customers: Keys, Limits, Versioning and Docs

Why offer an API, and what it adds

Our guide to API integrations looks at the other side: your business calling services such as payment providers and CRMs. Here you are the provider. Your customers, or developers they hire, write code that calls your app, and you have to keep that working for years. The main references used below are the OWASP Top 10 API Security Risks (2023), the OpenAPI Specification 3.2.0 (the current version, released September 2025), RFC 9110 (HTTP Semantics) and RFC 6585, which defines the 429 status code.

An API lets customers build your product into their own processes and automate around it, which tends to make it harder to replace. It also adds work that a normal web app does not have:

• an access system for machines, separate from staff logins;
• limits so one customer's script cannot slow the app down for everyone;
• a promise not to change things under people's code;
• documentation that developers outside your company can follow without asking you.

If the app serves many client companies from one system, the API has to respect the same separation between them as the screens do. Our guide to multi-tenant SaaS explains that separation.

Access: API keys and OAuth

There are two common ways to let code in.

API keys suit a customer connecting their own systems to their own account. A key is a long secret string that the customer's code sends with each request. Good practice on the provider side is to let customers create, name and revoke their own keys in your app's settings, to tie each key to one account, to let keys carry only the permissions the job needs (read-only, for example), and to record when each key was last used, so old ones can be spotted and removed. Treat keys as you would passwords in storage and in logs.

OAuth 2.0 suits a different case: a third-party product, such as an integration marketplace app, acting for many of your customers. RFC 6749 describes it as a framework that "enables a third-party application to obtain limited access to an HTTP service", either on behalf of the resource owner after an approval step or on its own behalf. The customer approves the connection on your site and never hands their password to the other product. OAuth is more work to build, so it is usually added when partners, not just customers, want to connect.

Both sit on top of your normal sign-in system. Our guide to user authentication for web apps covers passwords, multi-factor login and sessions for people.

Every request is checked, not just the login

A valid key proves who is calling. It does not prove they may see the record they asked for. OWASP ranks Broken Object Level Authorization first in its 2023 list, and among its prevention steps says to use the authorization mechanism "to check if the logged-in user has access to perform the requested action on the record in every function that uses an input from the client to access a record in the database". In practice: if a request asks for invoice 1043, the app checks that invoice 1043 belongs to the caller's account before returning it.

The same list warns about Broken Function Level Authorization: admin-only actions that a normal key can reach because the check was missed. And Broken Object Property Level Authorization covers fields a caller should not see or change, such as a price or an account status sent in a request body. These are design rules for the developer, but they are worth asking about by name.

Rate limits and the 429 response

OWASP's Unrestricted Resource Consumption entry notes that APIs use bandwidth, CPU, memory and storage, and that some calls trigger services "paid for per request", such as email or SMS. Its prevention advice includes:

• a limit on how often a client can call the API within a set period (rate limiting), tuned to business needs, with stricter limits on some endpoints;
• limits on how often one client can run a single sensitive operation;
• maximum sizes for strings, arrays and uploads;
• server-side checks on the parameter that sets how many records come back in one response;
• spending limits, or at least billing alerts, on the third-party services the API triggers.

When a client goes over a limit, the standard reply is 429. RFC 6585 says the 429 status code "indicates that the user has sent too many requests in a given amount of time" and that the response "MAY include a Retry-After header indicating how long to wait before making a new request". RFC 9110 defines Retry-After as either a date or a number of seconds. Publishing your limits and sending Retry-After lets well-behaved customer code slow down by itself instead of failing.

Clear errors and safe retries

Developers judge an API by its errors. RFC 9110 gives each common status a meaning: 400 for a request the server will not process because of a client error, 401 when the request "lacks valid authentication credentials", 403 when the server "understood the request but refuses to fulfill it", and 404 when the resource is not found. It also allows a server that wants to hide that a forbidden resource exists to answer 404 instead of 403, which suits records belonging to other accounts. Pair each status with a short message saying what was wrong.

Networks fail mid-request, so callers retry. RFC 9110 calls a method idempotent when sending the same request several times has the same intended effect as sending it once; PUT, DELETE and the safe methods such as GET are idempotent. It says a client "SHOULD NOT automatically retry a request with a non-idempotent method" unless it has a way to know the request is safe to repeat. POST, used to create orders or payments, is not idempotent, so if retries matter, give callers a way to make a create request safe to repeat, so a retry does not create a duplicate.

Versioning and retiring old versions

Once customers' code depends on a field name or a response shape, changing it breaks their systems. The usual approach is to keep additions backwards compatible (new optional fields are fine) and to put breaking changes in a new version, running old and new side by side for a published period before the old one is switched off.

Old versions are also a security issue. OWASP's Improper Inventory Management entry mentions "deprecated API versions and exposed debug endpoints" and advises protecting "all exposed versions of your APIs, not just for the current production version". When a new version fixes a security problem, it says to decide whether the fix can be added to older versions or whether clients must be moved to the latest version quickly. Keep a list of every API host, its environment (production, staging, test) and its version, as OWASP recommends, and avoid using production data in non-production API deployments.

Documentation with OpenAPI

The OpenAPI Specification is the common format for describing an HTTP API. The specification says it lets "both humans and computers to discover and understand the capabilities of a service" without the source code, and that a description can be used by "documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases". The description is a JSON or YAML document, and an operation can be marked deprecated to tell consumers to stop using it.

OWASP gives a list of what to document: "authentication, errors, redirects, rate limiting, cross-origin resource sharing (CORS) policy, and endpoints, including their parameters, requests, and responses". It also suggests generating documentation automatically from open standards as part of the build, so the docs change when the code does. Beyond the reference, customers need a short getting-started page, a changelog and a way to reach you.

A launch checklist

• Customers can create, limit and revoke their own keys; OAuth if partners will connect.
• Every endpoint checks the record and the action against the caller's account.
• Rate limits and size limits are set, published and answered with 429 and Retry-After.
• Errors use the right status code and a readable message.
• Create requests can be retried without duplicates.
• A versioning rule and a retirement notice period are written down.
• An OpenAPI description, generated in the build, backs the public docs.
• An inventory lists every API host, environment and version.

Frequently asked questions

Does every web app need a public API?

No. It is worth building when customers keep asking to connect your app to their own systems, or when partners want to build integrations. It adds access control, limits, versioning and documentation work, so it is usually added once there is real demand.

Should I use API keys or OAuth?

API keys suit customers connecting their own systems to their own account. OAuth 2.0, described in RFC 6749, suits third-party products that act for many of your customers, because each customer approves the connection without sharing a password.

What should the API return when a customer sends too many requests?

The 429 Too Many Requests status code from RFC 6585, which may include a Retry-After header saying how long to wait. RFC 9110 allows Retry-After to be a date or a number of seconds.

How long should old API versions keep working?

There is no standard period; set one, publish it and keep to it. While an old version runs, OWASP advises protecting every exposed version, not just the current one, and checking whether security fixes need to reach older versions.

What is an OpenAPI description used for?

It is a JSON or YAML file describing your API in a standard format. According to the OpenAPI Specification, tools can use it to generate documentation, client and server code, and tests.

Planning an API for your web app or SaaS product? See our web app development service and all our services, or email [email protected].