Authentication

The Coastly Partner API authenticates every request with a secret API key sent as a bearer token. There are no cookies or sessions; each request stands on its own.

curl https://coastly.surf/api/v1/properties \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxx"

A request without a valid key returns 401 with the unauthorized error code.

Creating a key

API keys are created in the Coastly vendor dashboard under Developers. When you create a key you choose:

• Mode — test or live (see below).
• Scopes — the resources and actions the key may use, for example reservations:read or rates:write.
• Rate limit — requests per minute for that key (default 120).

The secret is displayed once, at creation time. Copy it immediately and store it in your secret manager. Coastly stores only a hash; if you lose the secret you must roll the key.

Test mode vs live mode

Every key is bound to one mode, encoded in its prefix:

Prefix	Mode	Resolves
ck_test_	Test	Test data only. Safe for development and CI.
ck_live_	Live	Real, production data.

A test key can never read or write live data, and a live key can never see test data. Build and run your integration end to end with a ck_test_ key, then swap in the ck_live_ key for production. The two modes are fully isolated, so nothing you do in test can affect live inventory, reservations, or invoices.

Scopes

Keys are least-privilege. A request to an endpoint your key is not scoped for returns 403 with the forbidden_scope error code. Scopes follow a resource:action shape:

Scope	Grants
properties:read / properties:write	Read / manage properties
room_types:read / room_types:write	Read / manage room types
availability:read / availability:write	Read / push availability
rates:read / rates:write	Read / push rates
reservations:read / reservations:write	Read / create, modify, cancel reservations
orders:read / orders:write	Read / create, update orders
invoices:read	Read invoices
commission:read	Read commission statements

Request only the scopes your integration needs. You can create multiple keys with different scopes, for example a read-only key for a reporting job and a read/write key for your booking service.

Managing keys safely

• Never expose keys in a browser, mobile app, or public repository. All calls must originate from your server.
• Use a distinct key per integration or environment so you can roll one without disrupting the others.
• Roll keys periodically and immediately if one may have leaked. Create the new key, deploy it, then delete the old key from the dashboard.
• Send keys only over HTTPS. Plain HTTP requests are rejected.

Errors

Authentication and authorization failures use the standard error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "req_8Kd2p1"
  }
}