Connect Stripe to Qoren with a restricted key

Connect Stripe once with a restricted key and your agents can wake the moment a payment fails, an invoice is paid or a subscription ends, with no webhook URL or signing secret to copy. Agents you give access to can also look up customers, invoices, subscriptions and payments in Stripe through Qoren's own tools.

Qoren keeps the key. It never reaches an agent's machine, and every Stripe action that moves money or ends a subscription waits for your approval. For how connections work in general, see connect your tools with Integrations.

Before you start#

• You are the owner of your Qoren organization. Only the owner connects tools, gives agents access and disconnects.
• You can create API keys in your Stripe account, under Developers in the Stripe Dashboard.
• Integrations is on for your account. It is still rolling out: if your sidebar has no Integrations under Capabilities, it is not on your account yet.

Make the key#

A restricted key lets you choose, resource by resource, what the key may read and write. Give it the least it needs.

1. In the Stripe Dashboard, open Developers, then API keys, and choose Create restricted key. Name it Qoren.
2. Set Webhook Endpoints to Write. That is how Qoren adds and maintains the one webhook endpoint your triggers use.
3. Set Read on what your agents should look up, for example Customers, Charges, Payment Intents, Invoices and Subscriptions. Reading an event also needs Read on the resource the event is about, so give Read on everything your triggers watch.
4. Leave everything else at None. Write access to money, such as refunds or payouts, is never needed to start. Add it later only if agents should refund, cancel or apply coupons, which always wait for your approval anyway.
5. Create the key and copy it. A live key starts with rk_live_, a test mode key with rk_test_.

Connect it in Qoren#

1. In the sidebar, under Capabilities, click Integrations.
2. Under Add a tool, click Stripe. The Connect Stripe dialog shows the same steps as above.
3. If your account works for clients, choose who it is for under Which client is this for?. A client's connection can only be used by that client's agents.
4. Paste the key into Restricted key.
5. Click Check key. Qoren asks Stripe about the key without saving anything, and Key checked lists what it found: the account, whether it can read, and Can add webhooks (N of 16 left).
6. Under What agents may do, choose Read only or Read and write.
7. Click Connect.

Screenshots of the dialog are in connect a tool.

What Qoren checks#

• The kind of key. A publishable key (pk_) is refused, and so is anything that does not look like a Stripe key. An unrestricted secret key (sk_live_ or sk_test_) is accepted, with a note that it can do anything in your account and that a restricted key is safer.
• That Stripe accepts it, by listing your webhook endpoints. A key Stripe rejects (deleted, expired or rolled) is refused.
• Room for a webhook. Qoren counts your existing webhook endpoints and event destinations against Stripe's limit of 16 and shows how many are left. If the key cannot read webhook endpoints, the check still passes, but it says Cannot add webhooks, so triggers need another key.
• Which account it is, from the account's display name, business name or email. Some restricted keys cannot read the account; then the check says so and the connection has no account name.
• Test or live mode, from the key itself. A test mode connection shows "(test mode)" after its name, and its triggers and tools only see test data.

Stripe does not tell anyone what a restricted key may write, so Qoren cannot check that up front. It finds out for real when you add the first trigger (that needs Webhook Endpoints: Write) and when an agent first tries a write.

Give an agent access#

No agent can use the connection until you give it access. Open the connection under Connected, pick the agent in Give access to…, choose its level and click Give access. You can narrow it to a few tools and change how many records it may read an hour. See give an agent access.

Events#

To have one of these wake an agent, open the agent's Triggers tab and add it under From your connected tools. See wake an agent from a connected tool. When you pick an event, Qoren estimates how often it happens from the last 30 days of your Stripe events, so you can choose a digest for a busy one.

How the webhook is set up. Stripe allows only 16 event destinations per mode, so Qoren uses one webhook endpoint per connection for every event and sends each event on to the triggers that want it. It adds the endpoint when you create the first trigger, with your account's default API version, and Stripe's own signing secret is kept encrypted by Qoren. Every delivery is checked against that secret and its signed timestamp, and anything older than five minutes is refused. Stripe retries a failed delivery, and Qoren recognises a retry by its event id, so an agent never handles one event twice.

What the agent receives. The event type and the object Stripe sent, trimmed to the fields an agent needs: amounts, currency, status, the customer, ids, dates and metadata. Stripe sends the whole object, so there is no extra read. The payload is labelled as data from outside; see how events reach the agent.

Tools agents can use#

There is no Stripe write an agent can make on its own: every one waits on the Approvals page with the exact amount and ids, whatever the agent's autonomy says. The writes also need the matching Write permission on the key itself; without it Stripe refuses and the agent is told. Reads count toward the agent's read cap. For the full safety model, see how Qoren keeps connected tools safe.

Limits and gotchas#

• 16 event destinations per mode. Stripe counts every event destination in that mode together: webhook endpoints, the newer event destinations, Amazon EventBridge and Azure Event Grid. Qoren counts both lists before adding its endpoint and never removes or replaces one of yours. If all 16 are taken, it says so plainly; delete one you no longer use in Stripe under Developers, Webhooks, then try again.
• One connection per Stripe account and mode. A test mode key and a live key of the same account are two separate connections, side by side, because Stripe keeps their data and webhook endpoints apart. A second key of a mode that is already connected is refused: use Replace key on that connection instead. Replace key also keeps the mode, so it refuses a test key on a live connection and the other way round.
• Disabled endpoints. Stripe disables an endpoint that keeps failing for several days, and events made while it was disabled are never resent. Qoren's daily check turns the endpoint back on in place, with the same signing secret, and creates it again if it was deleted.
• Stripe's agent keys. If you tagged the key as an agent key when you created it, Stripe may hold some writes, such as refunds, for its own approval as well.

Troubleshooting#

• "That is a publishable key." You copied the publishable key. Create a restricted key and paste that instead.
• "Stripe did not accept this key." It was deleted, expired or rolled, or not copied in full. Create a new restricted key.
• "This Stripe account is already connected here. Replace its key instead." A key of the same account and mode is already connected. Open that connection and click Replace key.
• "This key belongs to a different Stripe account." when you replace a key. The new key is for another account, or for the other mode (a test key on a live connection, or the other way round). Connect it as its own connection instead.
• Adding a trigger fails because the key cannot manage webhook endpoints. In Stripe, edit the restricted key and set Webhook Endpoints to Write, then try again.
• The connection says Needs a new key. Stripe stopped accepting the key, its triggers are paused, and you got an email. Replace the key and they come back by themselves. See when a connected tool stops working.
• The connection says Needs attention. Qoren could not put its webhook endpoint right, most often because the account has no room left or the key lost Webhook Endpoints: Write. Fix that in Stripe and click Check again.

Disconnect and delete the key#

1. Open the connection under Connected and click Disconnect.
2. In Disconnect Stripe?, click Disconnect (or Keep it to back out).

Qoren deletes the stored key, removes the webhook endpoint it added, removes every agent's access and pauses the triggers that used Stripe. It cannot revoke the key at Stripe, so do that too: in Stripe, open Developers, API keys and delete the restricted key, or expire it.