Skip to content
Gateway Stream

Getting Started

Authentication

Every client call carries one header. That header also decides which environment you reach.

Authenticate with an API key in the x-api-key header. There is no OAuth flow, no token exchange and no session to keep alive.

A fully authenticated request 
GET /api/v1/properties?limit=20 HTTP/1.1
Host: api.gatewaystream.com
x-api-key: gws_sandbox_8f3c1d9a7b2e4056
Accept: application/json

Your Keys

Gateway Stream issues your keys. You will normally hold two — one sandbox, one live — and the prefix tells them apart:

  • gws_sandbox_… — sandbox. Staging data, supplier test endpoints, test bookings.
  • gws_live_… — live. Production data and real reservations.
  • gws_… — an older key issued before the split. Treated as sandbox.

The prefix only routes the request. The key must also exist in that environment's own records, so renaming a sandbox key to look live does not make it live — it makes it a 401.

Knowing Which Mode Answered

Every client response carries an x-gws-mode header reading sandbox or live. It is worth asserting on in your own test suite — it is the cheapest guard against a staging deployment that quietly picked up a production key.

Response headers 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
x-gws-mode: sandbox

GET /me returns the same information in the body, along with the client name.

When Authentication Fails

401 unauthorized
The x-api-key header is missing, or the key is unknown, inactive or does not exist in the environment its prefix points at.
429 rate_limited
Too many requests from this key. details.retryAfterSeconds says how long to wait.
503 mode_unavailable
The key points at an environment this server has no configuration for — most often a live key against a deployment that only runs sandbox.
401 response body 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing x-api-key header",
    "requestId": "req_01JD8QC4R7M2K5VX"
  }
}

A 401 never says why in detail, on purpose: an attacker should not be able to use the error text to work out whether a key exists.

Rotating a Key

Ask Gateway Stream for a replacement, deploy it, then ask for the old one to be revoked. Revocation takes effect immediately, so do it in that order rather than the reverse. Keys are shown once when they are created and cannot be read back afterwards.