> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Store the API keys, tokens, and connected accounts your Pearl uses to sign in to external services.

![PearlVibe asking to connect a Slack account](https://mintcdn.com/nlpearl/SoAGEIboomvcxL-Y/images/dark_mode/credentials-cover.png?fit=max\&auto=format\&n=SoAGEIboomvcxL-Y\&q=85\&s=d6afe6d5be647fb1d43f90f1a06241da)

***

## Introduction

**Credentials** are the API keys, tokens, and connected accounts your Pearl signs in with when it calls an external service: your CRM, your calendar, Slack, or your own API. You set a credential up once, then pick it in every node that needs it, instead of pasting a key into each request.

> [card] Connected accounts
>
> Connect Google, Microsoft, Slack, HubSpot, Salesforce, and more through their own sign-in.

> [card] Keys and tokens
>
> Add an API key, a bearer token, a username and password, or a token the platform renews for you.

***

## Credentials Overview

Credentials belong to a **Pearl**: every node of that Pearl can use them, but other Pearls can't. Like the rest of your Pearl, they are saved with its **version**: a change you make in a draft only reaches live calls once you publish it.

> [!NOTE]
>
> Some credentials are set by the platform for your workspace. They appear in every Pearl's list with a lock (**Set by the platform: nothing to edit**), and can be used but not edited.

#### Accessing Credentials

Click the `{ }` button (**Variables & credentials**) in the header of the Pearl editor, then select **Credentials** in the dialog.

![Variables & credentials button in the editor header](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-cred-open.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=003ca4e32b7e6a1531146bf62bfcef02)

The list shows each credential's **Name**, **Type**, and **Status**. Use the search field to find a credential by name.

![The Credentials section of the Variables & credentials dialog](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-cred-list.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=fdf77d4cfcf040cae46f657706244bc2)

| Status | Meaning |
| - | - |
| **Ready** | The credential is complete and can be used. |
| **Not connected** | The account still has to be connected: open the credential and click **Connect**. |
| **Reconnect needed** | The account's token lacks some of the scopes asked for: click **Reconnect** to grant them. |
| **Values missing** | A value is empty: fill in every value. Until then, API calls can't sign in with it. |

***

## Adding a Credential

Click **Add credential**. The **Add a credential** panel opens with two ways to add one: **Add manually**, or pick an **integration** from the list. Use **Search integrations** to find one.

![The Add a credential panel with Add manually and the list of integrations](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-cred-add.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=8fffab801ca9ffb1c974402e7607a6ef)

### From an integration

Each integration of the catalog shows how it signs in (**OAuth 2.0**, **API key**, **Bearer token**…), or **Connected** when your Pearl already has a working credential for it (**Connected · 2** if it has two).

**1. Pick the integration**

Click the integration. A credential is created for it and opens in the panel. Some integrations first ask for **Secure values**, such as your app's client ID and secret or your shop domain.

**2. Connect the account**

Click **Connect**. A window opens on the service's own sign-in page: sign in and grant access. When you're done, the window closes and the credential is **Ready**.

> [!NOTE]
>
> Clicking an integration always creates a new credential, even if you already have one for it. To use a second account of the same service, add the integration again and connect the other account.

### Manually

Click **Add manually**, enter a **Name** (a label to recognize it later, up to 100 characters), and choose a **Type**. The form shows the fields of that type.

| Type | What you enter |
| - | - |
| **Api Key** | Where the key goes (**Header** or **Query**), its **Key**, and its **Value**. |
| **Basic Auth** | A **Username** and a **Password**. |
| **Bearer** | The token, without "Bearer". It is sent as `Authorization: Bearer <token>`. |
| **Custom Api Key** | Your own **Headers**, **Query params**, and **Body** values. |
| **Refresh Token** | The request that gets a token. The platform fetches it, adds it to your calls, and renews it before it expires. |

> [!NOTE]
>
> The type can't be changed once the credential is saved: to sign in another way, create a new credential. **OAuth 2** accounts are connected through their integration, not added manually.

#### Configuring a Refresh Token credential

![Refresh Token credential form with its token request and token settings](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-cred-form.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=5ebbc1e5c22016a81350f06776c585e1)

| Field | Description |
| - | - |
| **Access token URL** | The method and endpoint used to request the token, with optional **Headers**, **Query params**, and **Body** (e.g. `grant_type`, `client_id`, `client_secret`). The Body is hidden for GET and DELETE. |
| **Path in the answer** | JSON path to locate the token in the response (e.g. `access_token` or `data.access_token`). |
| **Lifetime (seconds)** | How long the token stays valid (minimum **100**, **300** by default). |
| **Header key** | Name of the header where the token is injected (**Authorization** by default). |
| **Header prefix** | Optional prefix for the token (**Bearer** by default). |

In **Test the token request**, click **Run test** to call the token endpoint. The result shows **Token ready** with the token, how it is sent, and how often it is renewed, or what went wrong. If the token is somewhere else in the answer, a button offers to use the path it found. Then click **Save**.

![Test the token request section of a Refresh Token credential](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-cred-test.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=35a99bdb6c0e21f6aadb36014c45e2a3)

> [!WARNING]
>
> Make sure **Path in the answer** matches the exact location of the token in the JSON response. If the platform can't find the token at this path, the credential fails.

#### Keeping a value out of sight

In a **Refresh Token** or **Custom Api Key** credential, keep a sensitive value, such as a client secret, out of the form: click the `{ }` button of a value (**Insert a secured variable**), add it as a **secured variable** (a key made of letters, numbers, `-` and `_`, and its value), and insert it as `{its key}`. Once saved, only its last two characters are shown.

***

## Managing Credentials

Click a credential in the list to open it.

* **Edit**: change its values, then click **Save**, or **Undo changes** to go back. Editing a connected account's settings disconnects it: click **Reconnect** afterwards.
* **Reconnect**: sign in to the account again, for example after its access was revoked.
* **Delete**: in the **…** menu, click **Delete credential**, then confirm. To delete several at once, tick them in the list and click **Delete**.

> [!WARNING]
>
> Deleting a credential can't be undone. Every node that used it shows **Credential not found.**, and the Pearl can't be published until you pick another credential in those nodes or turn their **Credentials** option off.

> [!TIP]
>
> Credentials are saved as soon as you click **Save**: no need to save the Pearl. If you change them on the live version, a new version is created for your changes (**New version created**), and the live version keeps taking calls until you publish.

***

## Using Credentials

#### In an API node

In the node's **Options**, turn on **Credentials** and pick one in **Token**. **Add New** opens your Pearl's credentials, and the pencil next to the selected one (**Edit**) opens its settings. See [API node](https://developers.nlpearl.ai/pages/api_action.md#credentials-authentication).

![Credentials turned on in the Options of an API node, with a token selected](https://mintcdn.com/nlpearl/_4HaLUueN6-xLPpT/images/light_mode/api-credentials.png?fit=max\&auto=format\&n=_4HaLUueN6-xLPpT\&q=85\&s=cff44d984a8d7d6f71522c137594b90c)

The platform adds the credential to each request. A **Refresh Token** is kept for its **Lifetime** and fetched again when it expires; if the API answers **401**, **403**, **419**, **440**, or **498**, the token is renewed and the request sent again once.

#### In an integration node

In the **Add Node** picker, the **Integrations** section lists the whole catalog, and marks **Connected** the integrations your Pearl already has a credential for. Picking one adds a node that uses that credential, or creates the credential if there's none yet.

![The Integrations section of the Add Node picker](https://mintcdn.com/nlpearl/kaHFRsr5ql_SypDO/images/light_mode/add-node-integrations.png?fit=max\&auto=format\&n=kaHFRsr5ql_SypDO\&q=85\&s=c1e700d4343a17ba729eb5001762f7ee)

#### With PearlVibe

When PearlVibe builds a step that needs an account, it asks for it in the chat with a card: **Connect Your … Account** for an account you sign in to, or **Set Up Your … Account** for keys. Click **Connect** and sign in, or fill in the keys and click **Save**; **Dismiss** skips it. If the sign-in window closes before you're done, click **Ask Pearl** next to **Having trouble?** and PearlVibe helps you.

#### When a credential fails during a call

If the platform can't get a token (an account to reconnect, a token request that fails), the API request isn't sent. The node then behaves as if the API had failed, and the error appears in the call's events. Publishing is also blocked while a credential used by a node isn't **Ready**: the errors panel lists it under **Credentials**, with a button to connect it or fill it in.

***

## Frequently Asked Questions (FAQ)

> [accordion] Are credentials shared between my Pearls?
>
> No. Each Pearl has its own credentials. Only the credentials set by the platform, marked with a lock, appear in every Pearl of the workspace.

> [accordion] What happens to credentials when I duplicate or transfer a Pearl?
>
> The copy gets the same credentials, values included, whether you duplicate the Pearl or transfer it to another workspace.

> [accordion] What happens when I copy nodes to another Pearl?
>
> Credential values never travel with copied nodes. On paste, each node keeps its credential if the target Pearl has it, or takes the target Pearl's credential for the same integration. Otherwise, you're asked to **Choose a credential again** on those nodes.

> [accordion] Can two credentials have the same name?
>
> Yes, but give each one a clear name (for example `Stripe production` and `Stripe test`) to pick the right one in your nodes.

> [accordion] How do I use a credential in the API?
>
> `GET /v2/Pearl/Credential/{pearlId}` returns the **Id** and **Name** of the published Pearl's credentials, never their values. Use an **Id** as the credential of an API action. See [Get Pearl Credentials](https://developers.nlpearl.ai/api-reference/v2/pearlFlow/get-pearl-credentials.md).

> [accordion] Where are the credentials of the Email node?
>
> The Email node doesn't use these credentials: it sends through the email providers of your workspace. See [Email node](https://developers.nlpearl.ai/pages/email_action.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.