Can a partner access our database directly?

No, and it is the first rule: a partner is a user with a role, going through the same services as your application, behind a gateway that checks their key, their rights per resource, their quota, the schema and idempotency, and logs every call. Database access gives everything, to everyone, without a trace, and cannot be revoked without breaking everything.

How do we limit what each partner sees?

Through a rights sheet signed on both sides and enforced by the server on every resource: the carrier reads orders to ship but not prices, the big client sees only its orders and invoices, the accountant reads and writes nothing. The documentation describes these rights; the server enforces them, and an out-of-rights attempt receives a 403 and a log line.

What happens if a partner calls too often?

They have a quota per minute and per day; beyond it, they receive a 429 with a Retry-After header saying how long to wait, and they lose nothing by retrying. If the overrun repeats, the quota is raised in writing, with a date. Your own customers are never slowed down by a partner’s script.

How is a partner told when something changes on our side?

Through webhooks: an event signed with HMAC-SHA256 and a timestamp, sent to their address, retried with a growing gap for up to three days if they do not answer 2xx, uniquely identified so that a duplicate changes nothing, and replayable from their portal. They can always re-read the state through the API: a webhook is an attempt, not a truth.

What happens when we change our API?

Version 1 changes only by addition: new fields or new routes, never a removal. If an incompatible change is necessary, version 2 is announced with a date, version 1 stays supported for twelve months, and a lagging partner receives an answer rather than an error. It is the policy large commerce platforms follow, written in your API contract.

How long to open an API to a first partner?

Ten weeks: one for the API contract, two for the gateway in front of existing services, one for the sandbox and documentation, two for webhooks, two for the first partner in sandbox then production, two to freeze version 1. The partner works alone for most of that time, with the documentation and their log.

Opening an API to your partners in Algeria in 2027: keys, rights, quotas, webhooks, versions and documentation, without exposing your system

Short answer. A partner is a user with a role, not an exception: they go through the same services as your application, and there is no special route. Between them and those services, a gateway applies six gates, identical for everyone: encrypted connection, a key or token per partner that can be revoked, read and write rights per resource, a quota per minute and per day with a 429 and a retry delay, a typed and versioned schema, an idempotency key on every write; and every pass or refusal leaves a log line. What changes on your side goes to them through signed webhooks, retried with a growing gap for three days, replayable from a portal. Version 1 is frozen and changes only by addition, with twelve months of support written down. Ten weeks, two of them before any partner sees anything.

This guide is for the manager asked for “an access” by a carrier, a big client or a firm, the founder settled in France whose platform must connect to software they do not know, and the IT manager who must say no to direct database access without blocking the business. It does not repeat how you connect to existing software yourself, described in the integration guide, nor how roles are built inside the application, described in the rights guide; it describes the reverse, what is built when others plug into you, and extends our page on software engineering.

What the large platforms say

Platforms that open APIs to thousands of partners publish their rules, and they transpose. On versions: a large e-commerce platform “releases a new API version every three months”, names each version by its date, guarantees it “not to change for its supported lifetime”, supports it “for a minimum of 12 months”, and when a partner calls a version that no longer exists, “falls forward and responds using the oldest accessible stable version” instead of rejecting them. What this imposes: a version changes only by addition, the next one has a written announcement date and end-of-support date, and a lagging partner receives an answer, not an error.

On webhooks, the documentation of a large payment platform says events are retried “for up to three days with an exponential back off”, that it “doesn’t guarantee the delivery of events in the order that they’re generated”, that your server must “quickly return a successful status code (2xx) before any complex logic”, and that duplicates are detected by the event id, never by the timestamp. The signature is an HMAC-SHA256 of the raw body prefixed by the timestamp, with a default tolerance of five minutes against replay, and the secret can be rolled with up to 24 hours of overlap during which two signatures are emitted. What this imposes: a webhook is an attempt, the partner acknowledges then processes, ignores what it has already seen, and can always re-read the state through the API.

On quotas, the HTTP protocol itself has the answer: status 429 “Too Many Requests”, defined by RFC 6585, with a Retry-After header saying how long to wait; and on keys, OAuth 2.0’s “client credentials” flow describes exchanging an identifier and a secret for a short-lived token, for a machine talking to a machine. What this imposes: a partner exceeding its quota loses nothing, it waits the stated delay; and a stolen key is revoked without touching the others. What we did not find: an Algerian or sector standard for APIs between companies; what we see is database access shared by e-mail, and we say so as an observation.

Connecting a partner, in six steps

Before the architecture, a partner’s path, from the request to the production key.

Figure 1 · Six steps, and the third is the one always skipped: writing what this partner may do, in read and in write, and how many times per minute, before they have written a line. Everything else, key, sandbox, review, is the implementation of that sheet.

Request and contract: the partner says what they want to read and write, how often, and both parties sign a rights sheet; it is what will settle the discussions. Account and test key: a partner account, a sandbox key, fake data that looks like the real thing, so they can build without touching anything. Rights and quotas written: read or write per resource, calls per minute and per day; it is the step always skipped, and the one that prevents the PATCH on a price at three in the morning.

Sandbox integration: the partner builds alone with the documentation, and their errors are in their own log, which they read without calling you. Review: the log reread together, errors explained, idempotency checked by resending the same write twice, webhooks acknowledged. Production key: activated on a date, with a starting quota raised on request, a first-week watch, and a rotation planned in the contract. Six steps, four of them where the partner works alone: that is the measure of a well-made API.

Three calls, one chain of gates

The security of an open API is not seen on a diagram but on three real calls, and on the gate where each one stops.

Figure 2 · Three partners, one chain of gates, and the same log line for every pass and every refusal. The carrier passes; the big client trying to change a price is stopped at the rights gate; the point-of-sale app exceeding its six hundred calls a minute receives a 429 with the delay before retrying, and loses nothing. The figures are a constructed example.

The carrier reads the orders to ship with its production key: encrypted connection, key recognised, read right on orders, quota respected, version 1 schema, no write so no idempotency key required; it receives forty-eight orders and the call is logged with its name, the route and the response time. The big client tries to change a price: its key is valid, but its role only grants creating orders and reading its invoices; it is stopped at the rights gate, receives a 403, the attempt is written and its contact is notified. No route was “forgotten”: the rule is enforced by the server on every resource, as the rights guide describes for internal users.

The point-of-sale app sends its 601st call of the minute: stopped at the quota gate, it receives a 429 and a Retry-After of twelve seconds; nothing is lost, it retries, and if this happens every day, the quota is raised in writing. The chain is identical for everyone, it is the only thing the partner sees of you, and it is the same gate as the one placed in front of an AI agent: a partner and an agent are two actors who propose actions, and the server disposes.

«The partner never sees your service or your database; it sees six gates, the same for everyone, and every pass or refusal leaves a line.»

An API open to partners, in five layers

Behind those three calls, five layers, and a rule in the third that holds all the others.

Figure 3 · The gateway is the accented layer, but the rule that holds everything is in the third: there is no special route for partners. A partner is a user with a role, going through the same services and the same rules; the gateway adds the key, the quota, the version and the log.

The partner: their ERP, their app, their script; you do not control their code, you control what they may ask and what they receive. The gateway: encrypted connection, keys and tokens, rights per resource, quotas, schema per version, idempotency, log; the layer that protects, identical for everyone, and the only one they see. Your services: the same as your application’s, orders, deliveries, invoices, catalogue; there is no “partner-special” route, and what a partner can do, a user with the same role can do too, nothing more; that is what keeps the API from becoming a second application to maintain.

Data: never exposed directly, filtered by role; the big client sees only its orders and invoices, the carrier does not see prices, and if your platform serves several clients, the isolation described in the multi-tenant SaaS guide applies. Portal and supervision: documentation generated from the schema, sandbox, keys and secrets managed by the partner themselves, log of their calls and webhooks, replay; what the partner reads alone instead of calling you, and what you read every week on a screen built like the manager’s dashboard.

Six partners, and what each is allowed to do

The rights sheet is the most useful document of the project, and it fits in six lines.

Figure 4 · Each row is a rights sheet signed on both sides, and the server applies it, not the documentation. The carrier does not see prices, the accountant writes nothing, the big client sees only itself; quotas are starting points raised on request, with a date. The values are an example.

The carrier reads orders to ship, addresses and time slots, never prices or margins; it writes delivery status, proof and incidents; it receives shipping and cancellation events; it is the link described in the delivery platform guide. The big B2B client reads its catalogue at negotiated prices, its orders and its invoices, nothing of others; it creates an order and cancels it before preparation; it is the B2B portal seen from its ERP. The accounting firm reads invoices, credit notes and payments per period, and writes nothing.

The reseller or marketplace reads available stock and reseller prices, creates orders and reserves stock for thirty minutes, and receives stock and price changes; it is the connection described in the marketplace guide. The third-party point of sale reads the catalogue and writes sales and closings, as the point-of-sale guide provides. The bank or aggregator reads nothing and writes nothing: it sends its signed webhooks and you verify them, per the payment guide. The quotas in the table are starting points; they are raised on request, with a date, and never silently.

One event delivered to a partner: signed, retried, acknowledged, replayable

Webhooks are the half of the API that quotes forget, and the half that wakes you at night.

Figure 5 · A webhook is an attempt. This one succeeded on the third, ten minutes after the event, because the partner’s server was restarting; the signed header was the same each time, the partner verified the signature and would have ignored a duplicate delivery. Large payment platforms retry for up to three days with a growing gap, do not guarantee order, and ask for a quick 2xx answer; we do the same.

The event order.shipped is created at 10:02 for the carrier. First attempt: its server does not answer within ten seconds. Second, a minute later: it answers 500, it was restarting. Third, at 10:12: 200, acknowledged. The gap between attempts grows, and attempts continue for up to three days; beyond that, the event is marked undelivered and the partner sees it in its portal, from where it can replay it. On every attempt the header is the same: event id, timestamp, HMAC-SHA256 signature computed with the partner’s secret over the timestamp and the raw body.

On the partner’s side, four gestures the documentation explains and the review checks: verify the signature on the raw body and reject a timestamp older than five minutes; answer 200 right away and process afterwards, in a queue; ignore an id already seen, because a duplicate delivery must change nothing; and re-read the state through the API when in doubt, because a webhook is an attempt, not a truth. The secret rotates with twenty-four hours of overlap, during which two signatures are emitted, so that no partner is cut off on a Friday evening.

«A webhook is an attempt, not a truth; the partner acknowledges, processes, ignores what it has seen, and re-reads the state when in doubt.»

Seen elsewhere: platforms that open APIs, and what transposes

Three sources say the essentials. The commerce platform that publishes a version every quarter and supports it for twelve months says how you change an API without breaking partners: by addition, with dates, and by answering those who lag; what transposes is the frozen version 1 and the deprecation policy written in the contract. The payment platform that retries for three days, does not guarantee order and asks for a quick 2xx says how you deliver events to servers you do not control; what transposes is the signature, the attempts, the event id and the replay. HTTP and OAuth say how you refuse cleanly and how you authenticate a machine; what transposes is the 429 with a delay and the revocable key.

What these sources do not say: what your partners are allowed to see at your end, and how many calls per minute your server can take; the rights sheet answers the first question, the sandbox load test the second.

The rules of an API you can open without fear

Six rules, written in week one. A partner is a user with a role, going through the same services; no special route. One key per partner, revocable on its own, with rotation planned. Rights are enforced by the server on every resource, not by the documentation. One quota per partner, with a 429 and a delay, raised in writing. Webhooks are signed, retried and replayable, and the partner can always re-read the state. The version is frozen: it changes only by addition, and the next one has dates.

A seventh rule concerns the quote: “API for partners” is not a requirement, it is a sentence; the requirement reads “rights sheet per partner type, read and write per resource; key or token per partner, revocation, rotation; quotas per minute and per day with 429 and Retry-After; versioned schema and documentation generated from the schema; idempotency key on every write; log of every call with partner, route, result; HMAC-signed webhooks with timestamp, attempts with a growing gap for up to three days, event id, replay from the portal; sandbox with fake data; versioning policy with twelve months of support; no direct database access”, and it is checked as the specification guide recommends. A quote proposing “read access to the database for the partner” has proposed failure number one.

Six companies, and the first partner they connect

Six companies we often equip, and for each the first partner who asked for “an access”.

The wholesaler and its portal, described in the dedicated guide. Its biggest retailer orders from its own software; it sees only its prices, and the stock it reserves is released after thirty minutes.
The delivery platform, described in the dedicated guide. Three online shops send it their orders and receive statuses; each has its key, and none sees the others.
The pharmaceutical wholesaler, described in the cold-chain guide. The laboratory reads the traceability of the batches it delivered, per batch, never per customer.
The marketplace, described in the dedicated guide. Sellers synchronise stock and prices from their point of sale; six hundred calls a minute for the largest, stock reservation on order.
The mobile app with its partners, described in the updates guide. The same add-without-remove rule serves old app versions and partners: it is one versioning policy.
The company run from France. The accounting firm in Algiers reads invoices and payments every evening through the API; the founder sees in their board who called what, and the monthly e-mailed file is gone.

The 2027 calendar

The calendar is that of an API opened in ten weeks, two of them before any partner sees anything.

Figure 6 · Ten weeks, two of them for the API contract and the gateway before any partner sees anything, and two for the first real partner. Version 1 is frozen at the end: it changes only by addition, and it is supported twelve months after the next one is announced, as commerce platforms that publish a version every quarter do.

Week 0 to 1 writes the API contract: resources, rights per partner type, starting quotas, versioning and deprecation policy; signed. Weeks 1 to 3 build the gateway in front of the existing services: keys and tokens, rights per resource, quotas, log; no new route. Week 3 to 4 opens the sandbox and the documentation generated from the schema, and the portal where the partner manages keys and reads its log. Weeks 4 to 6 build the webhooks: events, signature, attempts with a growing gap, replay.

Weeks 6 to 8 connect the first real partner, a carrier or a big client, in sandbox then in production, with the log reread together every week. Weeks 8 to 10 freeze version 1: it now changes only by addition, twelve months of support are written, and version 2 will exist only if a change requires it. Every batch is demoed as the delivery guide describes, and the idempotency key on every write follows the principle of offline synchronisation: a write sent twice counts once.

What makes a partner API fail

The APIs we take over almost always failed for one of these reasons.

Direct database access. The partner reads everything, sometimes writes, and nobody knows what.
One key for everyone. It leaks at one partner, and everyone is cut off to change it.
Rights in the documentation, not in the server. “Please do not call this route” is not a control.
No quota. A badly written script at the partner calls a thousand times a second, and your own customers wait.
Webhooks with no signature or retry. Anyone can send one, and the real one is lost at the first outage.
A field removed without a date. Three partners crash the same morning, and none had been warned.
No sandbox. The partner tests in production, with real orders, and you discover their errors at your customers.

Frequently asked questions

The questions we receive from managers, founders and IT managers.

Can a partner access our database directly?: No, and it is the first rule: a partner is a user with a role, going through the same services as your application, behind a gateway that checks their key, their rights per resource, their quota, the schema and idempotency, and logs every call. Database access gives everything, to everyone, without a trace, and cannot be revoked without breaking everything.
How do we limit what each partner sees?: Through a rights sheet signed on both sides and enforced by the server on every resource: the carrier reads orders to ship but not prices, the big client sees only its orders and invoices, the accountant reads and writes nothing. The documentation describes these rights; the server enforces them, and an out-of-rights attempt receives a 403 and a log line.
What happens if a partner calls too often?: They have a quota per minute and per day; beyond it, they receive a 429 with a Retry-After header saying how long to wait, and they lose nothing by retrying. If the overrun repeats, the quota is raised in writing, with a date. Your own customers are never slowed down by a partner’s script.
How is a partner told when something changes on our side?: Through webhooks: an event signed with HMAC-SHA256 and a timestamp, sent to their address, retried with a growing gap for up to three days if they do not answer 2xx, uniquely identified so that a duplicate changes nothing, and replayable from their portal. They can always re-read the state through the API: a webhook is an attempt, not a truth.
What happens when we change our API?: Version 1 changes only by addition: new fields or new routes, never a removal. If an incompatible change is necessary, version 2 is announced with a date, version 1 stays supported for twelve months, and a lagging partner receives an answer rather than an error. It is the policy large commerce platforms follow, written in your API contract.
How long to open an API to a first partner?: Ten weeks: one for the API contract, two for the gateway in front of existing services, one for the sandbox and documentation, two for webhooks, two for the first partner in sandbox then production, two to freeze version 1. The partner works alone for most of that time, with the documentation and their log.