Use your own Anthropic and OpenAI API keys

While Oyma provides full on-device AI summaries and note Q&A via Ollama, many users want access to state-of-the-art frontier models like Anthropic’s Claude 3.5 Sonnet or OpenAI’s GPT-4o for complex reasoning, multi-language synthesis, and executive summaries.

Oyma supports a strict Bring-Your-Own-Key (BYOK) model. You connect directly to AI providers using your personal developer credentials, storing keys in the macOS Keychain and paying wholesale token prices with zero vendor markups.

Why Bring-Your-Own-Key is superior to AI subscriptions

Most note-taking applications charge a flat $10 to $20 per seat per month for AI features, reselling commercial API access at huge markups. The BYOK architecture in Oyma provides three major advantages:

1. Wholesale pricing: You pay only for the exact tokens you consume directly on your Anthropic or OpenAI invoice. Summarizing a 45-minute meeting typically costs less than two cents.
2. Zero middleman data exposure: Requests travel directly from your Mac to the provider’s API endpoint over TLS. No third-party server intercepts or logs your meeting content.
3. Data retention control: Foundation model providers offer developer enterprise terms where API data is not used for model training by default.

Token economics comparison

The table below contrasts standard fixed SaaS subscription models with the direct developer API costs utilized by Oyma:

Metric / Dimension	Bundled SaaS AI Add-on	Oyma BYOK (OpenAI GPT-4o mini)	Oyma BYOK (Claude 3.5 Sonnet)
Monthly Base Cost	$10.00 – $20.00 / user	$0.00	$0.00
Cost per 30-min Call	Bundled (soft caps apply)	~$0.004	~$0.018
Cost for 20 Meetings/mo	$10.00 – $20.00 flat	~$0.08 / month total	~$0.36 / month total
Middleman Proxy Server	Yes (vendor inspects text)	None (direct socket connection)	None (direct socket connection)
Custom Model Selection	Locked to vendor default	User selectable	User selectable
Training Policy	Varies by vendor TOS	Zero training on developer API	Zero training on commercial API

How to configure your API keys

Step 1: Obtain a developer key from your provider

You will need an active developer account with Anthropic or OpenAI.

Setting up Anthropic Claude

1. Navigate to the Anthropic Console at console.anthropic.com.
2. Create an account or sign in to your existing developer team.
3. In the sidebar, select API Keys and click Create Key.
4. Provide a descriptive label such as Oyma-MacBook and click Create.
5. Copy the secret key string immediately (it begins with the prefix sk-ant-api03-). Anthropic will not display the key again once the dialog closes.

Setting up OpenAI GPT

1. Navigate to the OpenAI Platform dashboard at platform.openai.com.
2. Select API Keys from the navigation menu.
3. Click Create new secret key, assign a name like Oyma-desktop, and click Create secret key.
4. Copy the resulting key string (it begins with sk-proj- or sk-).

Step 2: Add the key to Oyma

1. Open Oyma and press ⌘, to open Settings.
2. Select the AI tab and click Configure… next to Provider & API keys.
3. Select your provider (Anthropic or OpenAI).
4. Paste your secret key into the API Key field.
5. Choose your default model (for example, claude-3-5-sonnet-20241022 or gpt-4o-mini).
6. Click Test connection. Oyma sends an empty validation ping to the provider endpoint. Once the status badge switches to Connected, click Save.

macOS Keychain security architecture

Security credentials must never be written to plaintext configuration files, database tables, or Markdown frontmatter. Oyma interfaces directly with the native Apple Security.framework to manage API credentials securely:

• Hardware-backed encryption: Keys are stored as generic password items (kSecClassGenericPassword) within your macOS Login Keychain, protected by your Mac user account password and Secure Enclave hardware encryption.
• Service namespace isolation: Keys are isolated under the distinct bundle identifier com.getoyma.app.ai-keys. Other applications running on your Mac cannot read these credentials without an explicit macOS authorization prompt.
• Accessibility flags: Keys are registered with kSecAttrAccessibleAfterFirstUnlock, meaning the secret key cannot be read from disk while your Mac is locked or booted in recovery mode.
• Zero plain text persistence: The key resides in encrypted memory only during the active HTTP request execution and is wiped from memory buffers immediately afterward.

Removing or rotating credentials

To revoke or update an API key at any time:

1. Open Settings → AI → Provider Settings.
2. Click Forget Key.
3. Oyma issues a native SecItemDelete call to the macOS Keychain, permanently purging the record from disk.
4. You can also inspect or delete the key manually using the macOS Keychain Access utility by searching for com.getoyma.app.ai-keys.

Direct network transport and zero-proxy guarantee

When you invoke an AI action—such as generating a meeting summary, extracting action items, or querying notes with Ask—the network request originates directly from your Mac’s networking stack:

[ Oyma on your Mac ] ──(TLS 1.3 / HTTPS Direct)──> [ api.anthropic.com ]
                                                    OR [ api.openai.com ]

There is no proxy server, no middleman caching tier, and no telemetry gateway. You can verify this architecture in real time using Oyma‘s built-in Egress log or external tools like Wireshark or Little Snitch.

Payload contents and privacy boundaries

Only the text explicitly required to answer your query is transmitted:

• For meeting summaries: The extracted Markdown transcript and your selected summary prompt template.
• For Ask note queries: The text snippets retrieved via your local SQLite vector or full-text index matching your search question.
• Source audio files, original media recordings, and unrelated notes in your vault are never transmitted to cloud endpoints.

Tracking token consumption and cost ceilings

Developer API usage is metered per token (roughly 4 characters of text). In Settings → AI → Usage & Costs, Oyma provides granular local accounting:

• Session counters: Tracks prompt tokens (input) and completion tokens (output) for every individual request.
• Cumulative expenditure: Calculates estimated dollar spend based on published provider pricing rates.
• Budget alert threshold: Set an optional local notification ceiling (e.g., alert when monthly spend reaches $5.00) to avoid surprise invoices from your model provider.

Troubleshooting common API errors

Status Code	Error Message	Common Root Cause	Recommended Solution
401	Invalid API Key	Key was revoked, typed incorrectly, or expired.	Check console dashboard, generate a fresh key, and re-enter in Settings.
429	Rate Limit Exceeded	Account tier limits hit or credit balance empty.	Verify that you have added a billing payment method with positive prepaid credits.
400	Context Length Exceeded	Meeting transcript exceeds model context window.	Switch to high-context models (Claude 3.5 Sonnet supports 200k tokens; GPT-4o supports 128k tokens).
503	Provider Service Overloaded	Temporary upstream outage at Anthropic or OpenAI.	Retry request after 30 seconds or toggle temporarily to local Ollama models.

To run AI summaries completely offline with zero network connectivity, read our comprehensive setup guide for on-device AI with Ollama. To learn how all outbound requests are audited, inspect our guide to the Egress log.