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

# API Access

> REST access to your Virtual APIs — authenticated fetch and marketplace relay.

# API Access

**Your Virtual API, one URL away.**

Every Virtual API is accessible over REST. How consumers connect depends on the [visibility level](./agents#visibility-levels):

| Visibility        | Endpoint                  | Auth                     | Registry                      |
| ----------------- | ------------------------- | ------------------------ | ----------------------------- |
| **Disabled**      | `/fetch/{leaseId}/{path}` | API key required         | No                            |
| **Private**       | `/fetch/{leaseId}/{path}` | API key required         | No                            |
| **Unlisted Open** | `/relay/{leaseId}/{path}` | Marketplace key required | No                            |
| **Listed Open**   | `/relay/{leaseId}/{path}` | Marketplace key required | Yes — discoverable in catalog |

<Info>
  **Private** Virtual APIs can also be accessed via the relay endpoint when the consuming organization has been authorized by the lease owner. See [Organization Authorizations](#organization-authorizations) below.
</Info>

## Private access (fetch)

Virtual APIs with **Disabled** or **Private** visibility use the fetch endpoint with an API key:

```
https://service.dataharbor.co/fetch/{leaseId}/{path}
```

Include the `dataharbor-api-key` header — you can find your API key in the Virtual API dashboard.

```bash theme={null}
curl -H "dataharbor-api-key: YOUR_API_KEY" \
  https://service.dataharbor.co/fetch/b097a4d3-44e6-4490-9f03-104f4d636e20
```

## Marketplace relay access

Virtual APIs with **Unlisted Open** or **Listed Open** visibility use the relay endpoint. Discovery can be public, but the current runtime still requires a marketplace API key (`mkp_...`) on relay calls:

You can create a marketplace key from the account settings page in DataHarbor.

```
https://service.dataharbor.co/relay/{leaseId}/{path}
```

The `{leaseId}` is the unique identifier for your Virtual API. The `{path}` maps to your upstream API's route structure — the same object matching and controls apply automatically.

```bash theme={null}
# List properties
curl -H "dataharbor-api-key: mkp_your_marketplace_key" \
  https://service.dataharbor.co/relay/166d4e26-3d40-4e44-806a-e56b93ebb121/properties

# Get a specific property's issues
curl -H "dataharbor-api-key: mkp_your_marketplace_key" \
  https://service.dataharbor.co/relay/166d4e26-3d40-4e44-806a-e56b93ebb121/properties/1/issues
```

<Tip>
  The fetch endpoint also works for **Unlisted Open** and **Listed Open** Virtual APIs — useful when you want authenticated access even on a publicly visible API.
</Tip>

**Unlisted Open** is ideal for partner-specific sharing. **Listed Open** goes further: your Virtual API appears in the DataHarbor registry and catalog, making it discoverable while still routing requests through marketplace-key enforcement.

## Organization Authorizations

Lease owners can authorize specific partner organizations for relay access to their Virtual API — regardless of visibility level. This enables controlled sharing without making the Virtual API publicly discoverable.

### How it works

1. **Authorize access** — The lease owner adds a partner organization by org ID from the **Marketplace Management** tab on the Virtual API detail page.
2. **Partner connects** — The authorized organization uses their existing marketplace key (`mkp_...`) on the relay endpoint. No new keys or auth types are needed.
3. **Usage is billed to the consumer** — Relay usage through an org authorization is billed against the **consuming organization's** marketplace quota, not the lease owner's.

```bash theme={null}
# Partner org uses their existing marketplace key
curl -H "dataharbor-api-key: mkp_partner_marketplace_key" \
  https://service.dataharbor.co/relay/b097a4d3-44e6-4490-9f03-104f4d636e20/customers
```

### Key details

* **No new credentials** — Partners reuse their existing marketplace key. No additional keys or auth types are introduced.
* **Any visibility tier** — Org authorizations work for Private, Unlisted Open, and Listed Open Virtual APIs. A Private lease with org authorizations is accessible via relay only to authorized organizations.
* **Instant revocation** — Authorizations can be revoked at any time from the Marketplace Management tab. Access is removed immediately.
* **Governance still applies** — All data controls, geo restrictions, expiration, and audit logging are enforced on org authorization relay requests.

<Tip>
  Organization authorizations are orthogonal to visibility. A **Private** Virtual API with org authorizations is not discoverable in the registry or catalog — only explicitly authorized organizations can access it via relay.
</Tip>

## Registry

Virtual APIs with **Listed Open** visibility are indexed in the DataHarbor registry:

* **Registry catalog**: [https://service.dataharbor.co/registry](https://service.dataharbor.co/registry)
* **OpenAPI spec** (with query information): [https://service.dataharbor.co/openapi/v1.json](https://service.dataharbor.co/openapi/v1.json)

## Governance still applies

Marketplace relay access doesn't mean ungoverned access. Every request through the relay endpoint still enforces:

* All controls (redact, tokenize, hash, transforms)
* Geo restrictions
* Expiration and shutdown
* Full audit trail

## Next steps

<CardGroup cols={2}>
  <Card title="Virtual API Visibility" icon="eye" href="./agents">
    Decide who can discover or relay into a Virtual API
  </Card>

  <Card title="Global Marketplace" icon="store" href="../marketplace/global">
    Understand discovery and marketplace relay behavior
  </Card>
</CardGroup>