Authentication & Authorization¶

Polyguard uses different authentication mechanisms depending on whether the caller is a mobile device, a web application, or a server-side API client. This page covers all three.

Mobile SDK: Hardware Attestation¶

All communication between the Mobile SDK and the Polyguard APIs relies on hardware attestation -- cryptographic proof that the request originates from a genuine, uncompromised device running a legitimate copy of the application.

REST API: Session Tokens¶

Server-side and web-based API calls for link management, log access, and user management require an active session token in the Authorization header.

Authorization: Bearer <session_token>

Obtaining a Session Token¶

There are two methods for obtaining a session token:

Method 1: JWT Exchange¶

If you have an existing Polyguard JWT for a PolyUser with a User Account, you can exchange it for a session token.

POST /api/v1/auth/token
{
  "grant_type": "jwt_exchange",
  "jwt": "<polyguard_jwt>"
}

The response includes a session token and its expiration time:

{
  "session_token": "pg_sess_...",
  "expires_at": "2026-02-24T12:00:00Z"
}

Method 2: SSO Token Exchange¶

If your organization uses an integrated SSO provider, you can exchange an access token from that provider for a Polyguard session token.

POST /api/v1/auth/token
{
  "grant_type": "sso_exchange",
  "provider": "microsoft_entra",
  "access_token": "<sso_access_token>"
}

The response format is the same as the JWT exchange.

SSO Integration¶

Polyguard supports federated single sign-on for Platform Operators and Business Users who want to authenticate their users through their existing identity provider.

Supported Providers¶

How It Works¶

1. The user authenticates with their organization's SSO provider (e.g., Microsoft Entra ID).
2. Your application receives an access token from the SSO provider.
3. Your application exchanges that access token for a Polyguard session token via the /auth/token endpoint.
4. Subsequent Polyguard API calls use the Polyguard session token.

This means your users never need separate Polyguard credentials -- they authenticate with their existing organizational identity, and Polyguard maps that identity to the appropriate User Account and permissions.

Role Mapping¶

When SSO is configured, Polyguard can map SSO groups or claims to User Account roles within the Polyguard object model. This allows you to control which users in your organization can create Links, access audit logs, or manage App configuration, all based on their existing SSO group memberships.

Web SDK Authentication¶

The Web SDK itself does not require separate authentication to display the trust check modal. The SDK is initialized with a Link URL (obtained via the REST API during the Preparation phase), and the trust check session is authenticated through the Link's own token.

const polyguard = new Polyguard({ appId: "your-app-id" });

// The link URL contains embedded session authentication
polyguard.startTrustCheck({ linkUrl: "https://api-global.polyguard.ai/link/..." });

Backend API calls that create the Link and retrieve results still require a session token, as described above.

Summary¶