/v1 must include a credential as a bearer token in the Authorization header. The credential is your API key, or a session token created with it:
Sec-WebSocket-Protocol header. See Session tokens.
REST requests
Include the header on every request:Bearer is case-insensitive, but the key itself is case-sensitive.
Stream handshake
The WebSocket endpoint at/v1/stream accepts the same header on its opening HTTP request. The key is validated before the upgrade, so a client without a valid key cannot open a connection.
Authentication errors
A missing, malformed, unknown or revoked key returns the same response, as does an expired or invalid session token:401. Instead, check that the key is set, sent in the correct header, and not revoked. For a session token, request a new one from your backend.
A
503 SERVICE_UNAVAILABLE means the key could not be validated at that moment and does not indicate a problem with your key. Retry with backoff and keep using the same key.Choosing a credential
Keep your API key on servers you control, because anyone can extract it from a web page or an app. A browser also blocks the response to a request with an API key, because the API sends CORS headers only on requests with a session token.
Session tokens
A session token is a short-lived credential that your backend creates with its API key for one signed-in user. The browser sends the token instead of the key, so the key never leaves your backend.- Your backend signs in its user and calls
POST /v1/session-tokenswith its key. The request specifies the origins your page is served from, and can include asubjectthat identifies your user and a lifetime inttlSeconds. - Your backend returns the
tokento the page. - The page sends the token as
Authorization: Bearer <token>on REST requests. On the stream, it passesmetastreams.v1and the token as WebSocket subprotocols. - Before
expiresAt, the page requests a new token from your backend. A token cannot be refreshed.
Browser
/api/metastreams-token is the route on your backend that creates the token.
Origins
Each request with a session token must come from one of the origins specified when the token was created. A request from any other origin, or without anOrigin header, returns 403 ORIGIN_NOT_ALLOWED. The API sends CORS headers on every response to a request with a session token, including an error response.
The origin check prevents one site from using a token created for another. A client outside a browser can set any Origin header, so create tokens only for users your backend has signed in.
Lifetime and revocation
A token is valid for 60 to 3,600 seconds, 900 by default. After it expires, requests with the token return401 UNAUTHORIZED, and stream connections the token opened close with code 1008 and the reason token expired.
A single token cannot be revoked. Revoking the key invalidates every token created with it within about 30 seconds.
Billing and limits
Requests with a session token count against the rate limit and credits of the key that created it. Creating a token costs one credit. Each token has its own stream limits of 20 connections, 20 subscriptions and 2,000 addresses, counted separately from its key. All the tokens of one key share a limit of 10,000 open connections. Only an API key can create a token. A request to create a token with a session token returns403 FORBIDDEN.
Public endpoints
GET https://api.metastreams.io/openapi.json returns the OpenAPI document without a key, so you can generate a client before you have one.