Contact Sync ID SSO Integration Guide

This guide is for external identity providers that want to authenticate users into Fintary via SSO while leveraging the Agent Sync ID. Our SSO service implements an OAuth 2.0 Authorization Code flow, exchanges the authorization code for tokens, and inspects one of those tokens for the claims described below. Because the configuration is not self-service, please send the requested details to your Fintary representative so we can complete the setup in our environment.

Information we need to configure your provider

• Provider name/slug – your internal identifier so we can reference the integration in Fintary.
• Account to map – confirm which Fintary account (customer tenant) the provider applies to.
• Authorization URL – including any tenant path segments.
• Token URL – used for code exchange.
• Client ID and secret – the confidential OAuth credentials you created for Fintary.
• Redirect URI(s) – any redirect URIs your IdP expects; Fintary will provide the URI(s) to register, but we need you to confirm what is allowed.
• Scopes and extra authorization parameters – provide every scope/value we should include during the authorization request.
• Token endpoint content type – tell us if your token endpoint expects application/json (some providers do) or the OAuth default application/x-www-form-url-encoded.

Contact Sync ID-specific configuration

When userResolution.type is set to contact_sync_id, the SSO service uses an agent sync identifier as the source of truth for user resolution. We will configure this section for you, but we need the following information about your tokens:

• Identity claim key – defaults to contact_id. This claim must contain the authoritative agent ID synced with our service. It must be unique per agent within the mapped Fintary account.
• Token source – tell us whether the agent claims appear in the access_token or the id_token. We can parse either, but the claim must exist in one of them.
• Role claim key – defaults to role. Provide the claim name whose value we should map to a Fintary role.
• Role to Fintary role mapping – a map from your role values to Fintary roles (account_admin, producer, data_specialist). We only use this when provisioning a new user. You can also omit these if you intend on providing these specific values by handling the mapping on your side.
• Creation flags – indicate whether we should create a new agent and/or a new user if no existing record is found. If either flag is false, users missing that record will fail to sign in.

Email fallback for users without a sync ID

Some account types never receive the identity claim — for example, a provider's internal/staff users who authenticate through a separate identity system and were never synced into contacts. If your provider is configured with userResolution.identityFallback: 'email', a token missing the identity claim doesn't fail outright: we instead resolve the user by their verified email address, the same way the email-based SSO integration does.

• email becomes a required claim for any user going through this fallback — if it's missing or invalid, the login fails.
• This path never reads or writes contacts. It only matches against existing users records (optionally scoped to the mapped account, depending on emailMatchScope).
• Whether a given login uses the sync-ID path or the email fallback is decided per-token: if the identity claim is present, the sync-ID path always runs; the fallback only applies when it's absent.
• This does not change automatic provisioning behavior for the sync-ID path — createContactIfMissing and createUserIfMissing still govern whether new agents/users are created when a sync ID is present but unmatched.

Token payload requirements

The selected token (per tokenSource) must contain:

Example payload embedded in an access_token:

{
  "contact_id": "crm-78901",
  "email": "jane.doe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "external_agent"
}

What happens during sign-in

Instead of 1 and 2, The user can also be forwarded from your system to https://api.fintary.com/oauth/callback?code=<code>&provider=<provider_slug>. We'll trigger the same exchange for tokens with your token endpoint using that code and your client_id and client_secret.

1. A user starts SSO from Fintary and is redirected to your authorization URL with an OAuth state tied to their account/provider combination.
2. After the user authenticates, your IdP calls Fintary’s redirect URI with an authorization code.
3. Fintary exchanges the code at your token endpoint using the provided client credentials and declared content type.
4. We inspect the configured token (access or ID token), decode the JWT payload, and read the identity, role, and profile claims.
5. We attempt to locate an agent in Fintary whose sync_id matches the provided identity claim:
   • If found, we use that agent.
   • If not found and createContactIfMissing=true, we create a new agent populated with the supplied identity fields. Otherwise, the login fails.
6. We ensure the agent is linked to a user:
   • If a linked user in our system already exists, we use it.
   • If no user is linked and createUserIfMissing=true, we create a user (requires email), assign the mapped role, and link it to the agent. Otherwise, the login fails.
7. We generate a token on our side for the resolved user, allowing the session to continue in Fintary.

Checklist before handing off configuration details

• Confirm the OAuth client and redirect URIs are created and enabled.
• Ensure your token payload includes every required claim with the expected names/casing.
• Provide the claim/value mapping for roles, including every possible value your IdP can send.
• Decide whether new agent and/or users should be created automatically when no match exists.
• Share the full set of configuration parameters outlined above with Fintary support.

Once we receive the information, we will set up the provider, test the flow with you, and advise when the agent sync ID-enabled SSO integration is ready for production use.