# Noé Public API

The Noé public API gives an approved integration programmatic access to a
conciergerie workspace: its **properties**, **reservations**, **availability
blocks** and the **pricing calendar**, plus **webhooks** so you can react to
changes without polling.

```
https://api.wearenoe.fr/v1
```

There is no separate sandbox: a key always reaches the workspace's real data, and
calendar writes are pushed to the connected OTAs. Start with read calls, then test
writes on one property the workspace sets aside for it.

These docs live at [docs.wearenoe.fr](https://docs.wearenoe.fr). You register apps
and manage credentials in the developer console at
[developers.wearenoe.fr](https://developers.wearenoe.fr).

## Start here: which are you building?

Two paths through these docs. Pick one now — it decides how you authenticate and
nothing else.

**Connecting one workspace?** You are integrating a conciergerie you work with, or
your own. They issue you an API key and you are calling the API in minutes: read
[Authentication](/authentication), then the [Quickstart](/quickstart). No developer
account, no review, no OAuth.

**Building an app many workspaces connect to?** You need each customer to authorise
you without handing over a key. [Register an app](/apps), then implement
[OAuth 2.0](/oauth).

| | Connect one workspace | Build an app |
| --- | --- | --- |
| Credential | API key, issued by the workspace | Access token, from OAuth |
| Setup for each new customer | They generate a key and send it to you | They click Authorise |
| Developer account | Not needed | Required |
| Noé reviews you | No | Yes, once per app |
| Time to first call | Minutes | A day or two, including review |

If you are unsure, start with an API key. Moving to OAuth later means adding the
authorization flow — the endpoints, scopes and payloads you have already written
against do not change.

Everything after these two paths — pagination, filtering, pricing, availability,
idempotency, rate limits, errors, webhooks and the whole API reference — is
identical either way, which is why it is documented once.

## How access works

Access is granted by the workspace, not by us on their behalf. Three things have
to line up before a request succeeds:

1. **Noé approves your app** and the scopes it may ever request.
2. **The workspace authorises you**, choosing which of those scopes to share and,
   optionally, restricting you to specific properties.
3. **The credential itself** — a key, or an access token — can be narrower again.

What a credential can actually do is the intersection of all three, and any one of
them can be withdrawn independently. That is worth understanding early, because it
explains most `403` responses: your app is approved for a scope, but this
particular workspace did not share it.

## What is not here

- **Guest identity** is behind its own scope (`reservations:guest_read`) and
  every read of it is recorded in an audit trail. Without that scope the `guest`
  field is simply absent from the response, and the request still succeeds.
- **OTA reservations are read-only.** The source of truth for an Airbnb or
  Booking.com booking is the channel itself. You can create and manage
  *availability blocks*, which is how you close dates for owner stays or
  maintenance.
- **Access codes, door codes and internal notes** are never exposed. There is no
  scope that returns them.

## Conventions

Everything on this API is consistent, so you only have to learn it once:

- JSON only, UTF-8, `snake_case` field names.
- Timestamps are RFC 3339 in UTC (`2026-08-18T09:30:00Z`); plain dates are
  `YYYY-MM-DD`.
- Money is always an integer number of **cents** plus a currency code — never a
  float.
- Lists are [cursor-paginated](/pagination).
- Writes require an [`Idempotency-Key`](/idempotency).
- Errors share [one shape](/errors).

## Next steps

- [Authentication](/authentication) — get your first request working.
- [Quickstart](/quickstart) — a working sync in about ten minutes.
- [Filtering and delta sync](/filtering-and-sync) — how to stay inside your rate
  limit as a workspace grows.