# Add a connection

Add a connection to tell Faustine where a deployment of your API runs and which credential values to use there. A gateway cannot serve an API that has no connection. For what a connection is, see [Connections](https://docs.faustine.ai/apis/connections/).

## Before you begin

- The API's analysis has finished and its **Authentication** tab has a strategy. See [Authentication](https://docs.faustine.ai/apis/authentication/).
- The deployment is reachable from the internet. Faustine calls it from its own servers, so `localhost` and private addresses do not work.
- You have the credential for this deployment. For a bot user, create a dedicated user for Faustine. Logins protected by multi-factor authentication are not supported.

## Add the connection

### Endpoint

1. In the portal, go to [**APIs**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fapis) and select your API.
2. Select the **Connections** tab, then **New connection**.
3. Enter a **Name**, such as `Staging`.
4. If this deployment holds real customer data, turn on **Production connection**. Tests never run against a production connection.
5. Enter the endpoint:
   - For REST, enter the **Base URL**, such as `https://staging.nimbuscrm.example`.
   - For GraphQL, enter the GraphQL endpoint itself in **Base URL**, such as `https://staging.nimbuscrm.example/graphql`.
   - For gRPC, enter the **Address (host:port)** with no scheme, and leave **TLS** on unless the server is on a private network.
6. Select **Continue**.

### Credentials and labels

1. In **Credentials**, enter the values the API's strategy asks for. The step names the strategy and links to the **Authentication** tab.
2. Select **Continue**.
3. In **Labels**, add any `key=value` tags that describe this deployment, such as `env=staging`. Labels are optional. Gateways route by them.
4. Select **Continue**.

### Test

1. In **Operation**, select the read operation this connection is tested with. Faustine suggests one that takes no required input.
2. If the operation needs input, enter it in **Input (JSON)**.
3. Select **Test connection**, then **Run test** in the dialog. The test is a real call to your API.
4. When the step shows **Reached the endpoint**, select **Review**.

If the step shows **Could not reach the endpoint**, read the error under it. You can select **Continue anyway** and fix the connection later. Gateways report it as degraded until a test passes.

### Review and create

1. In **Review & create**, check the name, the endpoint, the credentials and the test operation.
2. Select **Create connection**.

Faustine creates the connection and tests it once more. The step shows **Connection created and reachable**. Select **All connections** to go back to the list, where the new connection appears with its status.

## Change a connection

To change a connection, select its row in the **Connections** tab. The page has four sections: **Endpoint**, **Credentials**, **Labels** and **Test call**. Change what you need and select **Save changes**. Secret fields are empty. Leave them empty to keep the stored value.

**Run now** in **Test call** calls the selected operation through the connection and shows the response.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| **Could not reach the endpoint** | The host does not resolve or does not answer from Faustine's servers. | Use a public host name. `localhost` and private addresses are not reachable. |
| `Address is host:port — no scheme (drop the http:// or grpc://).` | A gRPC address was entered as a URL. | Enter `host:port` only, such as `api.nimbuscrm.example:443`. |
| `Plaintext connections need “Allow plaintext (insecure)” switched on.` | **TLS** is off for a gRPC connection. | Turn on **TLS**, or turn on **Allow plaintext (insecure)** for a development server. |
| The connection is marked **needs credentials** | The API's strategy changed and this connection lacks a value it needs. | Open the connection and fill in **Credentials**. |

## Next steps

- [Add an API to a gateway](https://docs.faustine.ai/agent-gateway/add-an-api/): serve the API through this connection.
- [Generate and run API tests](https://docs.faustine.ai/apis/tests/): exercise the API's operations against a connection that is not production.
- [Connections](https://docs.faustine.ai/apis/connections/): the default connection, labels and importing several connections.