curl -X POST "https://api.metastreams.io/v1/session-tokens" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900}'
const response = await fetch("https://api.metastreams.io/v1/session-tokens", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ origins: ["https://app.example.com"], subject: "user-42", ttlSeconds: 900 }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { token, expiresAt } = await response.json();
use serde_json::{Value, json};
let response: Value = reqwest::Client::new()
.post("https://api.metastreams.io/v1/session-tokens")
.bearer_auth(std::env::var("API_KEY")?)
.json(&json!({ "origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900 }))
.send()
.await?
.error_for_status()?
.json()
.await?;
let token = &response["token"];
{
"token": "metasession_AbC...",
"expiresAt": 1789632915120
}
REST
Session tokens
Creates a short-lived credential that a browser sends instead of an API key.
POST
/
v1
/
session-tokens
curl -X POST "https://api.metastreams.io/v1/session-tokens" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900}'
const response = await fetch("https://api.metastreams.io/v1/session-tokens", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ origins: ["https://app.example.com"], subject: "user-42", ttlSeconds: 900 }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { token, expiresAt } = await response.json();
use serde_json::{Value, json};
let response: Value = reqwest::Client::new()
.post("https://api.metastreams.io/v1/session-tokens")
.bearer_auth(std::env::var("API_KEY")?)
.json(&json!({ "origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900 }))
.send()
.await?
.error_for_status()?
.json()
.await?;
let token = &response["token"];
{
"token": "metasession_AbC...",
"expiresAt": 1789632915120
}
Creates a session token, a short-lived credential that a browser sends instead of an API key. This endpoint requires an API key, and each successful call costs one credit. Session tokens describes how a backend and a browser use it.
Request body
originslists 1 to 10 origins allowed to use the token, each in the format of the browser’sOriginheader, such ashttps://app.example.com.subjectis an optional label for the user, such as a user ID, of 1 to 128 characters without control characters.ttlSecondsis the token’s lifetime, from 60 to 3,600 seconds. The default is 900.
Response
token is an opaque string of a few hundred characters that starts with metasession_. Treat it as a secret, and do not parse it. expiresAt is the expiry time in Unix milliseconds. Tokens cannot be refreshed, so create a new token before expiresAt.
Errors
| Code | When |
|---|---|
VALIDATION_ERROR | No origin or more than 10, a value that is not a valid origin, a subject or ttlSeconds out of range, or an unknown field |
FORBIDDEN | The request used a session token instead of an API key |
ORIGIN_NOT_ALLOWED | The request used a session token from an origin that the token does not allow |
curl -X POST "https://api.metastreams.io/v1/session-tokens" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900}'
const response = await fetch("https://api.metastreams.io/v1/session-tokens", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ origins: ["https://app.example.com"], subject: "user-42", ttlSeconds: 900 }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { token, expiresAt } = await response.json();
use serde_json::{Value, json};
let response: Value = reqwest::Client::new()
.post("https://api.metastreams.io/v1/session-tokens")
.bearer_auth(std::env::var("API_KEY")?)
.json(&json!({ "origins": ["https://app.example.com"], "subject": "user-42", "ttlSeconds": 900 }))
.send()
.await?
.error_for_status()?
.json()
.await?;
let token = &response["token"];
{
"token": "metasession_AbC...",
"expiresAt": 1789632915120
}
Authorizations
Send an API key, or a session token a key minted, as Authorization: Bearer <credential>. A browser opening /v1/stream offers its session token in Sec-WebSocket-Protocol instead.
Body
application/json
The body of POST /v1/session-tokens.
The origins the token may be presented from, 1 to 10, each as a browser sends Origin.
Required array length:
1 - 10 elementsExample:
["https://app.example.com"]
Who the token is for, in the caller's own terms: at most 128 characters, no control characters.
Maximum string length:
128Example:
"user-42"
How long the token lives, 60 to 3600 seconds; 900 when absent.
Required range:
60 <= x <= 3600Example:
900
Response
The token, and when it expires. Present it as Authorization: Bearer <token>, or on the stream handshake in Sec-WebSocket-Protocol beside metastreams.v1, from one of its origins.