> For the complete documentation index, see [llms.txt](https://docs.nerovasystems.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nerovasystems.com/guides/zero-to-live/step-5-connect-platform.md).

# Step 5: Connect your platform

Attach a provider connection: the record that tells Nerova where your Provider API v1 implementation lives and which credential to present.

{% hint style="info" %}
Requires [Step 4: Provision a tenant](/guides/zero-to-live/step-4-provision-tenant.md).
{% endhint %}

**Step 5 of 10.** The tenant from step 4 exists but points at nothing. In this step you attach a provider connection: the record that tells Nerova where your Provider API v1 implementation lives and which credential to present when calling it.

## 5.1 What a connection is

A connection binds one tenant to one provider implementation. It carries:

* **Provider type.** `ProviderApiV1` for a platform implementing the published contract from step 3.
* **Base URL.** The HTTPS endpoint you chose in step 3, registered on the connection in the console. This is a console step today; it is not part of the machine contract.
* **Credential.** The secret Nerova presents on every inbound call to your implementation. It is write only: you can set it and replace it, but no API ever returns it.
* **Merchant mapping.** Your `externalMerchantId` and `externalLocationId` so requests reach the right merchant in your system of record.

## 5.2 Create the connection

```bash
curl -X POST https://api.nerovasystems.com/api/v1/tenants/{tenantId}/connections \
  -H "Authorization: Bearer $NEROVA_API_KEY" \
  -H "Idempotency-Key: 0d5f7c21-63a4-4bd0-b9d2-8a1e5c33f0aa" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ProviderApiV1",
    "displayName": "My platform",
    "externalMerchantId": "merchant-42",
    "externalLocationId": "location-1",
    "timeZone": "Africa/Johannesburg",
    "currency": "ZAR",
    "credential": { "apiKey": "the-secret-your-endpoint-expects" }
  }'
```

The response describes the connection without echoing the credential:

```json
{
  "id": "pconn_...",
  "provider": "ProviderApiV1",
  "state": "PendingValidation",
  "health": "Unknown",
  "certificationState": "Unverified",
  "credentialVersion": 1,
  "capabilities": [],
  "version": 1
}
```

## 5.3 Validate before store

Nerova validates the credential against your endpoint before it is accepted; a credential that fails validation is rejected rather than stored. Watch `state` move from `PendingValidation` to `Active` by reading the connection back. If it lands on `Invalid`, fix the credential or your endpoint's authentication and replace the credential (a dedicated replace operation bumps `credentialVersion`; rotation never loses history).

The `health` field is Nerova's live view of your endpoint: `Healthy`, `Degraded`, or `Unavailable`. Fail closed applies from the start: an unhealthy connection is never used for writes.

## 5.4 Connect a test tenant

No connection is pre-seeded. To continue before your own implementation is finished, point the connection at the reference provider sample from step 3, hosted somewhere Nerova can reach over HTTPS. When your real endpoint is ready, repeat this step against your own tenant with your real base URL and credential.

## Where you are now

Your tenant has an Active connection. Nerova can reach your platform, but it does not yet trust what your manifest claims: nothing is verified. That is the next step.

Continue to [Step 6: Verify capabilities](/guides/zero-to-live/step-6-verify-capabilities.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nerovasystems.com/guides/zero-to-live/step-5-connect-platform.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.