Skip to content
WAMP Cloud

Exchange an app assertion for an installation bearer

POST
/auth/app-installation-token
curl --request POST \
  --url https://example.com/auth/app-installation-token \
  --header 'Content-Type: application/json' \
  --data '{ "assertion": "eyJhbGciOiJFZERTQSIsImtpZCI6InYxIn0.eyJpc3MiOiJhY21lLWNoZWNrb3V0LWJvdCIsInN1YiI6ImFjbWUtY2hlY2tvdXQtYm90IiwiYXVkIjoiaHR0cHM6Ly9hcGkud2FtcC5kZXYvYXV0aC9hcHAtaW5zdGFsbGF0aW9uLXRva2VuIiwiaWF0IjoxNzg2MTk1MDAwLCJleHAiOjE3ODYxOTUzMDB9.9tS1oQ2vKcYy8mB0dR4nZq7fXw3LhJp5A6TgEuVbNsC", "installationId": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65", "resourceAudience": "wamp-cloud" }'

The assertion is an Ed25519 JWT signed by the App’s registered private key. The returned token has audience wamp-cloud, is bound to one live installation, and is never a browser credential.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
assertion
required
string
>= 20 characters <= 4096 characters
installationId
required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid
Example
{
  "assertion": "eyJhbGciOiJFZERTQSIsImtpZCI6InYxIn0.eyJpc3MiOiJhY21lLWNoZWNrb3V0LWJvdCIsInN1YiI6ImFjbWUtY2hlY2tvdXQtYm90IiwiYXVkIjoiaHR0cHM6Ly9hcGkud2FtcC5kZXYvYXV0aC9hcHAtaW5zdGFsbGF0aW9uLXRva2VuIiwiaWF0IjoxNzg2MTk1MDAwLCJleHAiOjE3ODYxOTUzMDB9.9tS1oQ2vKcYy8mB0dR4nZq7fXw3LhJp5A6TgEuVbNsC",
  "installationId": "e3f7b219-6c40-4a8e-b591-07d2c48f3a65",
  "resourceAudience": "wamp-cloud"
}

Responses

Section titled “Responses”

200

Section titled “200”

Installation token minted

Media typeapplication/json

Result of exchanging a signed App assertion for the installation-scoped bearer that every /v1 request carries.

object
success
required

Always true on this response; a refused exchange returns an HTTP error status with an error code instead

boolean
token
required

The bearer to send as Authorization: Bearer <token>, bound to the one installation and one exact resource audience named in the exchange

string
expiresIn
required

Token lifetime in seconds from issuance, currently 600; mint a new token before this elapses rather than caching it longer

integer
>= 1
Example
{
  "success": true,
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImNsb3VkLTIwMjYtMDgifQ.eyJhdWQiOiJ3YW1wLWNsb3VkIiwiaW5zdGFsbGF0aW9uSWQiOiJlM2Y3YjIxOS02YzQwLTRhOGUtYjU5MS0wN2QyYzQ4ZjNhNjUiLCJpYXQiOjE3ODYxOTUwMDIsImV4cCI6MTc4NjE5NTYwMn0.Kx7Rd0uPnJ4wLbQ9mZaE2sT6yVfHgCiO5r1XjB3NtAe",
  "expiresIn": 600
}

400

Section titled “400”

Malformed request

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "invalid_request"
}

401

Section titled “401”

Missing, expired or wrong-audience bearer

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "unauthorized"
}

403

Section titled “403”

Live installation, scope or organization policy denies the operation

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "insufficient_scope",
  "requiredScope": "wamp.cloud.sessions:create"
}

429

Section titled “429”

The pre-authentication edge budget or durable human-membership/App-installation budget is exhausted

Media typeapplication/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object
error
required

Stable machine code

string
requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string
retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer
>= 1
key
additional properties
any
Example
{
  "error": "cloud_rate_limit_exceeded",
  "retryAfterSeconds": 3
}

Headers

Section titled “Headers”
Retry-After
integer
>= 1
RateLimit-Policy
string

IETF HTTPAPI structured quota policy

RateLimit
string

IETF HTTPAPI structured current service limit