Skip to main content
By the end of this page, your actor calls an API that needs a key, and the key stays out of everything the public can read. Most products worth selling call a service like that: a social network, a data provider, a model host. An actor’s code, its state and every call to it are public, so a key can’t go in any of them. Instead it goes in Cowboy’s secret store, and the actor marks where it belongs. A runner, the machine that makes the request for the actor, fills it in at the last moment. It takes four pieces: the code, a manifest, a deploy and the key.

1. Mark where the key goes

runner.secret(name, prefix=..., suffix=...) stands in for the key. The job the actor sends carries only the text around it, and the runner puts the value in when it makes the request. It works in a URL, a header or the request body:
For an API that takes its key in the URL, wrap the whole URL: url=runner.secret("YOUTUBE_API_KEY", prefix="https://...&key="). Pass the URL as url=, because the secret can’t fill a positional argument. A test sees the secret’s name and where it goes, never a value. In a SimulatedChain test, the last job’s secret_slots lists them:

2. Allow the host

Web requests need the http.fetch permission, which names the hosts the actor may reach. Ask for it in a manifest, saved as manifest.json in the project:
Name only the hosts you call. A request to any other host is refused.

3. Deploy

Output
The manifest is fixed at deploy. To reach another host later, deploy again with a new manifest. --max-spend-usd caps what the deploy takes from your wallet. --no-owner-funding keeps the actor from drawing on your wallet when its own balance runs short, or pass --owner-funding-cap-usd to allow it up to a limit (Keep it funded).

4. Add the key

Add the key for the address deploy printed. The command never takes the value: it opens a page on Cloud where you type it, and the page encrypts it before saving it.
Output
Readers lists the actors the key is released to. Only those actors’ jobs can use it.
Coming soon: adding a key without a browser, so a coding agent or a script can do this step.
A new deploy gets a new address, so when you ship a new version with cowboy deploy --new, add the key for the new address too.

Whose key a listed actor uses

The key you add is yours. Every hirer’s requests go out with it, so they all count against your account with that service and its rate limits. Set the actor’s @limit with that in mind, and pick a service whose terms allow it.
Coming soon: listings that ask each hirer for their own key during setup, and hires that run their own copy of your actor with your key.
What a key can and can’t protect against, from a hirer’s side, is in Your keys and your data.

Next