Credential Types
Different buildings let you in with different passes: some need a swipe card, some a wristband, some you sign in at the front desk, and some you open with your own house key. Connecting to an outside service works the same way — each service expects a particular kind of pass. Nirvai supports five, and this guide helps you pick the right one without needing to understand the technical details.
Why it matters
Every outside tool — Gmail, Stripe, Slack — has its own way of checking that a request is really allowed. If you hand it the wrong kind of pass, the connection simply won't work. Knowing which type your service expects saves you from guessing, and in most cases you won't have to choose at all: a template or the AI Assistant picks it for you.
How it works
Here's each type at a glance, with the everyday object it's most like.
| Type | It's like… | When you'd use it | Effort |
|---|---|---|---|
| API key | A membership card number | Most services that hand you one code (Stripe, OpenAI, Trello) | Easy |
| Bearer token | A VIP wristband | AI services, Discord bots, simple token-based services | Easy |
| OAuth | "Log in with Google" | Google, Microsoft, Slack, HubSpot, GitHub | Medium |
| Basic | A username and password | WooCommerce, older services | Easy |
| Facebook sign-in (Meta) | Signing in to connect your own page | WhatsApp, Instagram, Messenger, Meta Ads | Easy |
Not sure which type your service uses? The AI Credential Assistant researches the provider and picks the right one for you automatically.
API key
An API key is a private password that lets Nirvai connect to a service on your behalf — a unique code that identifies your account. You create it in the service's settings, paste it into Nirvai, and your agent quietly includes it on every request, like showing a membership card number to prove who you are.
Image: The API key credential form showing the key field, location selector, and key identifier
What you'll fill in:
| Field | What it means | Example |
|---|---|---|
| Label | A name so you can recognize this connection later | "Stripe Production" |
| API Key | The private code from your service | sk_live_abc123... |
| Location | Where the code is attached to the request | Header (most common) |
| Key Identifier | The name the service expects for the code | X-API-Key, Authorization, api_key |
Common services: Stripe (payments), OpenAI (GPT and DALL-E), Trello (project boards), SendGrid (email), Anthropic (Claude).
Bearer token
A bearer token is a secure access pass sent along with every request. It works much like an API key, but follows a standard format where the word "Bearer" is placed in front of the pass. Think of it as a VIP wristband at an event — whoever wears it gets in, no name check needed, which is exactly why you keep it secret.
Image: The bearer token credential form showing the token field and header name
What you'll fill in:
| Field | What it means | Example |
|---|---|---|
| Label | A name so you can recognize this connection later | "Discord Bot Token" |
| Token | The access pass from your provider | xoxb-abc123... |
| Header Name | The prefix the service expects (usually "Bearer") | Bearer, Token, Bot |
Common services: Discord (bot tokens), Notion (integration tokens), Linear, Airtable.
OAuth
OAuth is the "Log in with Google" style of connecting — you sign in with your own account on the service's own login page, instead of handing over your password. It's like giving a valet your car key: they can drive your car (access your data), but they don't have your house keys or know your address (your password). You can take their access away anytime.
Image: The OAuth2 credential form showing client ID, client secret, scopes, and redirect URI
How it goes:
- Set up a connected app in the service's developer console (Google Cloud Console, Slack API, and so on).
- Copy the Client ID and Client Secret the service gives you, and paste them into Nirvai.
- Add the Redirect URL that Nirvai shows you to your app's list of allowed return addresses.
- Click Authorize — a popup opens where you sign in to the service and approve the permissions.
- Nirvai saves the connection and keeps it fresh for you.
What you'll fill in:
| Field | What it means | Who fills it |
|---|---|---|
| Label | A name so you can recognize this connection later | You |
| Client ID | Identifies your connected app | You (from the provider) |
| Client Secret | The secret key for your connected app | You (from the provider) |
| Scopes | The permissions your agent gets (for example, read email, send messages) | AI or You |
| Redirect URL | The address the service returns to after you sign in — copy it exactly | Filled in for you |
| Sign-in & token addresses | The service's login page and the address Nirvai uses behind the scenes | AI fills these |
The Redirect URL has to be added to your connected app exactly as Nirvai shows it. Even a tiny difference — like an extra slash at the end — will make sign-in fail.
Common services: Google (Gmail, Calendar, Sheets, Drive), Microsoft (Outlook, Teams, OneDrive), Slack, HubSpot, GitHub, Shopify (also needs your store address).
Staying connected: OAuth sign-ins expire from time to time. Nirvai refreshes them automatically whenever the service allows it. If that ever fails — some services don't support it, or the connection has been idle too long — you'll just sign in again from the Managing Credentials page.
Basic
Basic uses a plain username and password, exactly like logging into a website. The two values are scrambled and sent securely with every request.
Image: The basic auth credential form showing username and password fields
What you'll fill in:
| Field | What it means | Example |
|---|---|---|
| Label | A name so you can recognize this connection later | "WooCommerce Store" |
| Username | Your account username (sometimes called a consumer key) | ck_abc123... |
| Password | Your account password (sometimes called a consumer secret) | cs_xyz789... |
Common services: WooCommerce (uses a key + secret as username and password), Jira (email + token), and older services that haven't moved to newer sign-in styles.
Facebook sign-in (Meta)
This is a special type just for WhatsApp, Instagram, Messenger, and Meta Ads. Instead of copying any codes, you sign in with your Facebook account and pick the page or account you want to connect — like linking your own social page in one click. Nirvai handles every technical detail behind the scenes.
Because there's no developer console to navigate, this is the simplest type to set up. It has its own short guide: Meta Platform Credentials.
Examples
Connecting OpenAI to generate text OpenAI hands you a single private code in your account settings. You'd create an API key connection, paste the code in, and you're done — no sign-in popup, no extra app to set up.
Connecting Gmail to send email on your behalf Gmail needs to know it's really you and that you approve. You'd use OAuth: a popup opens, you sign in to Google, approve the permissions, and Nirvai stays connected — refreshing the link automatically so you don't have to sign in again every day.
Common mistakes
| Mistake | Why it's a problem | Better approach |
|---|---|---|
| Picking a type by guessing | The connection silently fails if the service expects a different one | Use a template or the AI Assistant — they pick the right type for you |
| Typing the redirect address slightly differently | Even a trailing slash makes OAuth sign-in fail | Copy the Redirect URL from Nirvai exactly, with no edits |
| Treating a bearer token like a public ID | Anyone who has it can act as you | Keep tokens and keys private, the same way you'd guard a password |
How to choose
If you're setting one up by hand, this quick path points you to the right type.
When in doubt, the AI Credential Assistant figures out the right type by researching the provider's documentation for you.
What's next
- Browse Templates — use a ready-made setup so you don't have to pick a type yourself.
- Meta Platform Credentials — connect WhatsApp, Instagram, Messenger, or Meta Ads.
- AI Credential Assistant — let AI research and set up any service for you.