API keys and secrets sound technical, but they are actually pretty simple.
An API key is a password that lets Rival connect to another service. A secret is the secure place where that password is stored. You'll encounter them when bringing your own AI model to Rival or when connecting something you build to an outside service. This guide explains what API keys and secrets are, when you need them, and how to use them safely.
What Is an API Key?
An API key is a password that allows one application to communicate with another. When a function, workflow, agent, or MCP server needs information from an outside service, that service needs a way to verify that you're allowed to access it. The API key provides that proof.
You get the key from the service you're connecting to, and it is tied to your account with that service.
Do I Need an API Key?
Not always. Many agents, workflows, and functions work without one. You only need an API key when:
You want to use your own AI model provider
You want to connect to a service that requires authentication
You are building something that retrieves data or performs actions in another system
If your build doesn't connect to an outside service, you may not need an API key at all.
Where You'll Use API Keys in Rival
There are two common places where you'll encounter API keys.
Bring Your Own Model (BYOK): Every agent runs on a model, which is the AI brain that powers it. Rival can provide the model for you, or you can bring your own by connecting a provider such as OpenAI, Anthropic, or another supported model provider. This is known as BYOK, short for Bring Your Own Key. When you use your own key, the model runs through your account with that provider. This can help reduce Rival usage costs and gives you direct control over your model usage.
Connect to External Services: Many of the things you build need to connect to another application to do their job.
Examples include:
Email providers
Data platforms
CRMs
Internal databases
Third-party APIs
In these cases, the outside service requires an API key before it will allow access. Without the key, that part of the build cannot run.
What Is a Secret?
A secret is a secure place to store an API key. Because API keys work like passwords, you should never place them directly in your code where they can be exposed or copied.
Instead, Rival allows you to store them as secrets. Think of it like the key to your house. You wouldn't tape it to the front door. You would keep it somewhere safe and use it only when needed. A secret does the same thing for your API key. It keeps the key protected while still allowing your function to use it when it runs.
How to Add a Secret
First, obtain the API key from the service you want to connect to. Most services make keys available in their Developer, API, or Settings section.
Once you have the key:
Open My Tools and select the function you're working on.
Click the Code tab.
Find the Secrets section.
Click Add Secret.
Give the secret a clear name, such as
OPENAI_API_KEY.Paste your API key.
Save.
Your key is now securely stored and available to the function when it runs.
How API Keys and Secrets Work Together
API keys and secrets each have a different job. The API key allows the connection. The secret protects the key. When your function runs, Rival retrieves the key from the secret behind the scenes and uses it to authenticate with the external service. The key stays hidden the entire time. You get the connection you need without exposing sensitive credentials.
Best Practices
Treat API keys exactly like passwords.
Never share them publicly.
Never paste them directly into code.
Store them in secrets whenever possible.
Remove or replace keys that may have been exposed.
Only create keys with the permissions you actually need.
If you believe a key has been compromised, generate a new one from the provider and update the secret with the replacement.
TL;DR
An API key is a password that lets Rival connect to another service. A secret is the secure place where that password is stored.
You'll most commonly use API keys when bringing your own AI model or connecting functions, workflows, and MCP servers to external services. When your build runs, Rival retrieves the key from the secret behind the scenes, allowing the connection to work while keeping your credentials protected.
