Start a human-authorized App installation
const url = 'https://example.com/api/apps/installation-intents';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"assertion":"eyJhbGciOiJFZERTQSIsImtpZCI6InYxIn0.eyJpc3MiOiJhY21lLWNoZWNrb3V0LWJvdCIsInN1YiI6ImFjbWUtY2hlY2tvdXQtYm90IiwiYXVkIjoiaHR0cHM6Ly9hcGkud2FtcC5kZXYvYXBpL2FwcHMvaW5zdGFsbGF0aW9uLWludGVudHMiLCJpYXQiOjE3ODYxOTQxMDAsImV4cCI6MTc4NjE5NDQwMH0.Qw2Ej9pLmXbTz4Ns0YuRfV7dHc1KaG6iP3oBvSyMlAr","resourceAudience":"wamp-cloud","capabilityIds":["wamp.cloud.access","wamp.cloud.sessions:create","wamp.cloud.sessions:read","wamp.cloud.turns:submit","wamp.cloud.repositories:read","wamp.cloud.publications:create"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/apps/installation-intents \ --header 'Content-Type: application/json' \ --data '{ "assertion": "eyJhbGciOiJFZERTQSIsImtpZCI6InYxIn0.eyJpc3MiOiJhY21lLWNoZWNrb3V0LWJvdCIsInN1YiI6ImFjbWUtY2hlY2tvdXQtYm90IiwiYXVkIjoiaHR0cHM6Ly9hcGkud2FtcC5kZXYvYXBpL2FwcHMvaW5zdGFsbGF0aW9uLWludGVudHMiLCJpYXQiOjE3ODYxOTQxMDAsImV4cCI6MTc4NjE5NDQwMH0.Qw2Ej9pLmXbTz4Ns0YuRfV7dHc1KaG6iP3oBvSyMlAr", "resourceAudience": "wamp-cloud", "capabilityIds": [ "wamp.cloud.access", "wamp.cloud.sessions:create", "wamp.cloud.sessions:read", "wamp.cloud.turns:submit", "wamp.cloud.repositories:read", "wamp.cloud.publications:create" ] }'The App signs this request with its registered Ed25519 key. The returned short-lived Account Center URL lets a human choose an organization and approve capabilities on one exact resource server; no installation exists before that approval.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Example
{ "assertion": "eyJhbGciOiJFZERTQSIsImtpZCI6InYxIn0.eyJpc3MiOiJhY21lLWNoZWNrb3V0LWJvdCIsInN1YiI6ImFjbWUtY2hlY2tvdXQtYm90IiwiYXVkIjoiaHR0cHM6Ly9hcGkud2FtcC5kZXYvYXBpL2FwcHMvaW5zdGFsbGF0aW9uLWludGVudHMiLCJpYXQiOjE3ODYxOTQxMDAsImV4cCI6MTc4NjE5NDQwMH0.Qw2Ej9pLmXbTz4Ns0YuRfV7dHc1KaG6iP3oBvSyMlAr", "resourceAudience": "wamp-cloud", "capabilityIds": [ "wamp.cloud.access", "wamp.cloud.sessions:create", "wamp.cloud.sessions:read", "wamp.cloud.turns:submit", "wamp.cloud.repositories:read", "wamp.cloud.publications:create" ]}Responses
Section titled “Responses”Installation intent created
Envelope returned when an installation handoff is created or polled.
object
Always true on this response; a refused request returns an HTTP error status with an error code instead
Current state of the handoff, safe to poll on an interval until it reports authorized or expired
object
The intent id, which is itself the unguessable invitation — treat it and the authorize URL as secrets
pending until a human approves, authorized once an organization has installed the App, expired once expiresAt has passed; polling never consumes an authorized result
When this handoff stops being usable — 15 minutes after creation while pending, extended to a 1-hour result window once authorized
Account Center URL to hand to a human so they can pick the organization and approve the requested capabilities
Present only while status is authorized; the durable installation id to persist and name in every later token exchange
Example
{ "success": true, "intent": { "id": "2f9c8d31-0b64-4a72-9e58-c31d7a6f0be4", "status": "pending", "expiresAt": "2026-08-12T09:15:00Z", "authorizeUrl": "https://account.wamp.dev/install/2f9c8d31-0b64-4a72-9e58-c31d7a6f0be4" }}Malformed request
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "invalid_request"}Missing, expired or wrong-audience bearer
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "unauthorized"}Live installation, scope or organization policy denies the operation
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "insufficient_scope", "requiredScope": "wamp.cloud.sessions:create"}The pre-authentication edge budget or durable human-membership/App-installation budget is exhausted
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Example
{ "error": "cloud_rate_limit_exceeded", "retryAfterSeconds": 3}Headers
Section titled “Headers”IETF HTTPAPI structured quota policy
IETF HTTPAPI structured current service limit