Connect an outside API
Ask your app to call a service that has an API, and understand the network limits, metering, and how keys are stored.
If the service you need is not in the list of connections, it may still offer an API — a way for other software to ask it for data or send it data. Booking systems, government registers, and tools built for one company usually have one. You describe what to fetch or send, and the builder adds the call to your app.
Ask for the call
Describe the data, the service, and the moment:
Show the availability for a chosen date from the booking system.
Send each new order to our warehouse system.
Check the licence register every morning and flag any that have expired.
The builder needs to know where the data lives and what identifies you to the service — the address and the key or token it gave you. It will ask for anything it still needs, and you can paste in the service's own instructions if you have them.
How you are asked for a key
When the app needs a key, the builder asks you for it. A list headed Needed by this app — not provided yet appears in the app's Settings → Secrets, showing the name the app expects and an Add value button beside it.
Only the app owner can add, replace or reclassify a credential. If you have invited someone to edit the app, they can see the names and whether a value is filled in, and they cannot add, change or remove one.
Where the call runs
Calls are made from AppHandle's servers, not from the visitor's browser. This handles the common case where a service refuses requests that come from a browser, and it keeps your key away from visitors.
Only a handle function — a small snippet the builder adds that runs on AppHandle's servers — can read the value you stored. The pages of your app never receive it, so a visitor cannot find it by looking at the page.
Network limits
- Public addresses only. AppHandle blocks calls to private and internal network addresses, including a server inside your office or home network.
- Web addresses only. Calls use a web address (http or https), and a call that does not get an answer in time is reported as a failure.
- Bounded responses. A very large response is refused rather than loaded whole, so ask for data in parts when the service offers a way to page through it.
If the service runs on a machine only your network can reach, it cannot be called from your app as it stands. Publishing it behind a public address with its own authentication is the usual way to make it reachable.
Keys and secrets
Store the key or token the service gave you in the app's Settings → Secrets (open the app in the Desk, then its Settings):
- The value is encrypted, and it is never shown again after you save it.
- Only a handle function can read it, and it is never sent to a visitor's browser.
- A credential belongs to one app, so another app — and anyone you invite to another app — cannot reach it. Use a clear name in capitals with underscores, such as BOOKING_KEY.
- Choose who may use it:
- Only me and my editors — your own key, used only by the parts of the app that run on AppHandle's servers.
- Anyone signed in to this app — people who sign in to your app can use it, but visitors who have not signed in cannot.
- Anyone using this app — anyone who can open the app can use it, including visitors who have not signed in. Only choose this for a key the app itself uses, and remember you pay for every call it makes.
- If you delete a credential, anything using it stops working until you add it again. If the service issues you a new key, replace the value in place; the app does not need to be rebuilt.
What the calls cost
Each call that reaches the service is metered — from your monthly included usage first, then your balance, per call. Current prices are on the pricing page.
The count is what matters most. Calling the service every time a page loads is expensive; checking once and reusing the answer, or refreshing on a schedule, keeps it low. A call your app makes to an outside address is open to anyone the app admits, and you pay for it, so keep it to the work the app needs. Each app can make up to 100,000 of these calls in a day.
Test it in Preview
Ask for the call, then try it in Preview. If the service rejects the request or returns something unexpected, describe what you saw in the chat and the builder will adjust it. A failed call is reported in the app so you can tell a rejection from an outage.
Where to go next
Use a connected service in your app covers how metered calls are counted, and Add AI to your app applies the same approach to an AI service.