Credentials
Using Credentials with Tools
Connect your saved credentials to agent tools so your agents can work with other services
A credential on its own is like a spare key sitting in a drawer — useful only once you put it in a lock. You unlock it by connecting it to a tool in your agent's setup. This page explains how credentials and tools work together, and how to link them. A credential is a saved login for an outside service — Nirvai keeps it so it can act there on your behalf — and a tool is an action your agent can take, like sending an email.
How it works
When your agent decides to use a tool (for example, "send an email"), the tool automatically loads the credential you've linked to it. The credential carries the login, so the tool can reach the other service on your behalf. Your agent never sees the raw credential — it just gets the result back.
Connecting a credential to a tool
- Open your agent in the builder (Edit in the Agents center).
- Choose Tools in the left menu.
- Add a tool or select an existing one.
- In the tool's settings, find the Credential dropdown.
- Choose the credential you want to use.
- Save your changes (each section saves on its own).
Image: Selecting a credential in the tool configuration dropdown
The dropdown only shows credentials that fit the tool. For example, a Gmail tool only shows credentials that sign in with a Google account.
If the dropdown is empty, you need to create a credential for that service first.
One credential, many tools
A single credential can power several tools across different agents. For example, one Google sign-in credential can be used by:
- A Gmail tool in your customer support agent
- A Google Sheets tool in your data entry agent
- A Google Calendar tool in your scheduling agent
If you update or re-connect the credential, every tool that uses it updates automatically.
One credential, many agents
The same credential can be shared across agents too. If three agents all need to send emails through Gmail, they can all point to the same Gmail credential — you don't need to create one per agent.
Tools that need a credential
Most tools that reach an outside service need a credential. Here are some common examples:
| Tool | What it connects with | What it does |
|---|---|---|
| Send Email (Gmail) | A Google sign-in | Sends emails from your Gmail account |
| Post Message (Slack) | A Slack sign-in | Posts messages to Slack channels |
| Create Contact (HubSpot) | A HubSpot sign-in | Adds contacts to your CRM |
| Send WhatsApp Message | A Meta (WhatsApp) connection | Sends WhatsApp messages from your business number |
| Get Orders (Shopify) | A Shopify sign-in | Looks up order data from your store |
| Generate Text (OpenAI) | An OpenAI API key | Asks OpenAI's models to write text |
Custom tools
When you build a custom tool (a tool that reaches your own service or another one not listed), you choose what kind of connection it needs during setup. The tool settings will ask you to:
- Pick the connection type (API key, bearer token, a "Log in with…" sign-in, a username and password, or a Meta connection — see Credential Types).
- Link a saved credential of that type.
- The tool will use that credential's details whenever it runs.
For Meta-type custom tools, choosing a credential fills in the connection details automatically — you don't need to enter them by hand.
Custom tools that reach a public service with no sign-in don't need a credential at all. Set the connection type to None during setup.
When a credential stops working
| Credential type | Why it might stop | What to do |
|---|---|---|
| Private code (API key) | The service expired or revoked it | Tool calls fail. Get a new code and update the credential |
| Bearer token | The service expired it | Tool calls fail. Get a new token and update the credential |
| "Log in with…" sign-in | Access renews on its own, but sometimes lapses | If it lapses, re-connect from the Managing page |
| Username and password | You changed your password | Update the credential with the new password |
| Meta | Connections don't usually expire | If something breaks, re-connect through Facebook sign-in |
When a credential stops working or is deleted, every tool using it stops working too. Check which tools depend on a credential before you change it. See Managing Credentials for details.
Troubleshooting
| Problem | Fix |
|---|---|
| The credential dropdown is empty | Create a credential for that service first — the dropdown only shows credentials that match the tool |
| My credential isn't in the dropdown | It may be the wrong type for this tool. The dropdown only lists credentials that fit, so create or pick the right one |
| The tool fails after working fine before | The credential may have stopped working. Open Managing Credentials, then update or re-connect it |
| My custom tool won't save without a credential | Either link a credential, or set the connection type to None if the service needs no sign-in |
What's next
- Managing Credentials — edit, re-connect, or delete your credentials.
- Use tools with agents — give a tool (and its credential) to an agent.