Provider connections: store an OpenAI API key encrypted

Store an OpenAI API key encrypted on Flowyn's servers, separately for test and live, and test whether OpenAI accepts it. Using it is optional.

What a provider connection is

A named, encrypted model provider credential for one environment. OpenAI is the supported provider today. Your agent does not have to use it: it can keep calling OpenAI, or any other provider, with its own keys, and still send telemetry to Flowyn.

Store a key

The key is write-only. No response, log, or event ever contains it; responses show only its last four characters.

curl -X POST https://api.flowyn.dev/v1/provider-connections \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: openai-production" \
  -d '{
    "provider": "openai",
    "name": "Production OpenAI",
    "credential": "sk-••••"
  }'

Test it

POST /v1/provider-connections/{id}/test makes one request to OpenAI's models list with a 5-second timeout and no retries, at most once every 30 seconds per connection.

outcome	Meaning
accepted	OpenAI accepted the key at `checked_at`.
rejected	OpenAI answered 401.
unverified	Anything else, such as a timeout. It proves nothing about the key.

Manage

Call	Effect
`GET /v1/provider-connections`	List connections in the environment.
`PATCH /v1/provider-connections/{id}`	Rename.
`PUT /v1/provider-connections/{id}/credential`	Replace the key; optional `expected_version`.
`DELETE /v1/provider-connections/{id}`	Delete.

Permissions

Storing, replacing, renaming, or deleting a key needs an API key with the reveal ability, or the admin role for a person. Testing needs the run ability. Reading needs read.

Next step

Back to the agent overview, or read the REST reference.