Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

OpenAI uses a long-lived API key for every endpoint (api.openai.com). Authsome stores the key encrypted in the local vault, injects it at request time through the proxy, and keeps it out of shell history, process listings, and environment dumps.

​
At a glance

Provider nameopenai
Display nameOpenAI
Auth typeAPI key
Flowapi_key
HeaderAuthorization: Bearer <key>
Key pattern^sk-[A-Za-z0-9_-]{20,}$
Proxy hostapi.openai.com
Env varOPENAI_API_KEY
Where to get a keyplatform.openai.com/api-keys

​
Get a key

Create a key in the OpenAI dashboard at platform.openai.com/api-keys. Keys start with sk- followed by at least 20 letters, digits, underscores, or hyphens. Authsome validates the format on input and rejects pastes that obviously aren’t keys: 
Error: This does not look like a valid OpenAI API key.
Hint: OpenAI API keys start with 'sk-' followed by at least 20 letters, digits, '_' or '-'.

​
Log in

uvx authsome login openai
A local browser form opens at http://127.0.0.1:7998. Paste the key into the masked input and submit. The terminal prints Successfully logged in to openai (default). On a headless machine without a graphical session, authsome falls back to masked terminal input via getpass. The browser bridge is skipped automatically when no display is available. Verify: 
uvx authsome get openai --field status
# → connected

​
Use the key

Run the agent under the proxy. The library tab is for embedding authsome inside a larger Python orchestrator. 
uvx authsome run -- python my_agent.py
Under the proxy, authsome sets OPENAI_API_KEY=authsome-proxy-managed in the child’s environment and injects the real key into outbound requests to api.openai.com. The child process never sees the actual value. With the OpenAI Python SDK, no code change is required: it reads the env var, makes the request, and the proxy substitutes the header on the way out.

​
Multiple keys

A personal key and a team key on the same machine: 
uvx authsome login openai --connection personal
uvx authsome login openai --connection team
Read either side: 
uvx authsome get openai --connection team --field api_key --show-secret
uvx authsome export openai --connection personal --format env
Pass --connection <name> on login and on every read command to keep two or more accounts on the same provider side by side. See Multiple connections per provider for the full pattern.

​
Rotate the key

To replace the stored key with a new one: 
uvx authsome login openai --force
--force overwrites the existing connection without removing it first. Pass --connection <name> to target a non-default connection. To invalidate the old key at OpenAI as well, delete it in the OpenAI dashboard before running --force.

​
Remove the key

uvx authsome logout openai             # remove local credential
uvx authsome remove openai             # remove local provider state entirely
API-key providers have no revocation endpoint, so revoke and remove are equivalent for OpenAI.

​
Override the bundled definition

To change the header shape, the proxy host, or the validation regex, drop a custom JSON at ~/.authsome/providers/openai.json: 
uvx authsome inspect openai > ~/.authsome/providers/openai.json
# edit the file
uvx authsome list   # openai now shows source=custom
User-registered files always win over bundled definitions. See Provider schema for every field.

​
Troubleshooting

SymptomLikely causeFix
Incorrect API key provided from OpenAIKey was revoked at OpenAIGenerate a fresh key and run uvx authsome login openai --force.
Key pattern rejected at loginPasted something other than a key, or pasted with whitespaceRe-copy the key from the OpenAI dashboard. Authsome trims trailing whitespace but not embedded whitespace.
SDK sees authsome-proxy-managed and failsRunning outside uvx authsome runUse authsome run or fall back to eval "$(uvx authsome export openai --format env)".
TLS error against api.openai.com under the proxymitmproxy CA not trustedSee Proxy networking.
For deeper diagnostics, see Token refresh (API keys don’t have refresh, but the page covers when a stored secret is rejected at runtime).

​
What’s next

Run agents with the proxy

Keep the key out of the agent’s environment entirely.

Multiple connections per provider

Keep two or more keys on the same provider side by side.

API-key providers

All bundled API-key providers.

Provider schema

Every field in a provider definition.