Use your site's sign-in provider with XCIM

Visitors sign in on your site with the provider you configure. Your backend sends their signed identity token to Emabled. Visitors then choose which emails they want on your published consent screen.

1. Register your site and client

In Company → Sites & apps, select your site, choose its provider and enter its web client ID. Link the site to your XCIM application and verify its domain. Register the exact HTTPS return URL on the same host and authorize that domain for consent presentation (consent_presentation_delegate). Publish your consent screen before testing.

Provider	Register in the provider console
Apple	Use your Services ID and the web return URL handled by your site. Support Apple's form POST response when requesting email. A verified private relay address is the address to which consent applies. Apple web setup
GitLab.com	Create an OAuth application on GitLab.com and register your site's callback. Request the `openid` and `email` scopes. GitLab OIDC setup
Yahoo	Configure a web client with email access and ES256 ID-token signing. Register your site's callback. Yahoo configuration
Slack	Register a Sign in with Slack redirect URL. Request the identity scopes `openid email` in a separate sign-in flow from Slack app installation and send the Emabled nonce. Slack setup
Twitch	Use the authorization-code flow with `openid user:read:email` and the session nonce. In the authorization request, URL-encode `{"id_token":{"email":null,"email_verified":null}}` as the `claims` parameter so both values appear in the signed ID token. Twitch setup
Google	Register your HTTPS callback on a Web application client, request `openid email` and send the session nonce. Use a Gmail account or a verified Google Workspace address on its signed hosted domain. Google site sign-in. For an existing Emabled-hosted callback: Google relay setup

The provider callback belongs to your site's sign-in flow. The XCIM return URL is where Emabled sends the visitor after they make their email choices. Keep credentials and code exchanges on your backend.

2. Start one XCIM session for the visitor

For Google, Apple, GitLab.com, Yahoo, Slack or Twitch, send this request from your backend using your site's source ID, its registered values and the visitor's address. Use a new idempotency key for each journey and reuse it when retrying the same request.

POST https://api.emabled.com/v1/consent-sessions
Authorization: Bearer <vendor token with consent-sessions:create>
Idempotency-Key: <unique request key>
Content-Type: application/json

{
  "issuance_profile": "oidc_hosted_consent",
  "identity_profiles": ["oidc-01"],
  "oidc_source_id": "src_REPLACE_WITH_YOUR_SITE_ID",
  "requested_recipient": "tester@example.com",
  "manifest_id": "urn:xcim:manifest:example-v1",
  "use_published_consent_screen": true,
  "return_uri": "https://shop.example/xcim/return"
}

Store the returned session ID, nonce, resolved manifest ID and hosted consent URI in the visitor's server-side session. Start an authorization-code flow with the provider for this site's client. Pass the returned nonce unchanged, request email, and use your OIDC library's state validation and supported PKCE flow. Emabled accepts identity evidence from the last ten minutes. If the provider reports an older sign-in time, ask the visitor to sign in again through the provider.

3. Verify identity, then open the consent screen

In your provider callback, validate the state against the visitor's session and exchange the authorization code. Send the resulting ID token from your backend to the endpoint for that same XCIM session.

POST https://api.emabled.com/v1/consent-sessions/<session_id>/identity-evidence/oidc
Authorization: Bearer <vendor token with identity-evidence:submit>
Content-Type: application/json

{"nonce":"<stored session nonce>","id_token":"<provider-signed ID token>"}

Wait for HTTP 200 with status: verified. Then redirect the visitor to the stored hosted_consent_uri. A 422 means identity verification failed. Check the provider, client ID, verified email and nonce. A 404 means the session or its eligible site binding is unavailable. Keep raw tokens out of URLs and logs.

4. Verify the first receipt

After the visitor chooses an option and returns to your site, look up the stored session on your backend. Retrieve the signed receipt when its ID is available. Verify its signature, application and resolved manifest, then check the current permission for the requested purpose. Confirm the receipt appears under your application's Activity tab. Repeat with an unselected option or cancellation to check your site's handling of that choice.

Open the first receipt guide and backend example · Implement EVP on your website