Intents

Intents

Intent tokens provide account-scoped authorization for web components, allowing browsers to access Gateway APIs on behalf of a specific account.

Create Intent Token

Generate a short-lived token for account-scoped operations:

POST /api/2.0/app/intent/{account:remote_id}
Authorization: Bearer YOUR_APP_TOKEN
Content-Type: application/json

{
  "scopes": [
    "webcomponent:integration-read",
    "webcomponent:integration-event",
    "webcomponent:integration-install"
  ]
}

Path Parameters

Parameter	Description
account:remote_id	The account’s remote_id (e.g., myapp_tenant_12345)

Request Body

Field	Type	Required	Description
scopes	array	✅ Yes	Array of webcomponent scopes

Available Scopes

• webcomponent:app-read - Read app info
• webcomponent:integration-read - List/view integrations
• webcomponent:integration-event - Execute integration events
• webcomponent:integration-create - Install integrations
• webcomponent:integration-update - Update integrations
• webcomponent:integration-install - Install/uninstall operations
• webcomponent:integration-schedule - Manage schedules

Response

Status: 200 OK

{
  "data": {
    "token": "intent_abc123xyz...",
    "expires_at": "2024-01-15T11:30:00.000000Z"
  }
}

Using Intent Tokens

Intent tokens enable embedded web components to access account-specific data:

// In your web application, generate intent token server-side
const intentToken = await fetch('/api/generate-intent', {
  method: 'POST',
  body: JSON.stringify({ accountId: 'myapp_tenant_12345' })
});

// Pass token to frontend web component
<gateway-integrations-component
  intent-token="${intentToken}"
  gateway-url="https://<GATEWAY_URL>"
/>

Complete Example

// Server-side: Generate intent token
public function generateIntentToken(Request $request)
{
    $accountRemoteId = 'myapp_' . $request->user()->id;

    $response = Http::withToken($this->gatewayAppToken)
        ->post("https://<GATEWAY_URL>/api/2.0/app/intent/{$accountRemoteId}", [
            'scopes' => [
                'webcomponent:integration-read',
                'webcomponent:integration-event',
            ]
        ]);

    return response()->json([
        'intent_token' => $response->json()['data']['token']
    ]);
}

// Frontend: Use intent token with web component
async function loadGatewayComponent(accountId) {
  // Get intent token from your backend
  const response = await fetch('/api/gateway/intent', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ account_id: accountId })
  });

  const { intent_token } = await response.json();

  // Initialize web component with intent token
  const component = document.querySelector('gateway-integrations');
  component.setAttribute('intent-token', intent_token);
  component.setAttribute('gateway-url', 'https://<GATEWAY_URL>');
}

Security Notes

[!IMPORTANT] Intent tokens should be generated server-side and passed to the frontend. Never expose your app-level access token in browser code.

Token Lifecycle:

1. User accesses your application
2. Your backend generates intent token for their account
3. Frontend receives intent token
4. Web component uses intent token to access Gateway APIs
5. Intent token expires (typically 1 hour)

Learn more about account management →