> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP in the EU, or send-us.ahasend.com as a US connection point forwarding to the EU. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Single Sign-On (SSO) with OpenID Connect

> Set up OpenID Connect single sign-on for your AhaSend team with Microsoft Entra ID, Google Workspace, Okta, Authentik or Zitadel. Available on the Max plan.

AhaSend single sign-on lets your team log in through an OpenID Connect identity provider; this guide walks through its setup.

Available on Max. See [plans and features](/docs/facts#plans-and-features).

<Tip>
  **Max plan Feature:** OpenID Connect SSO is available exclusively on the [Max plan](https://ahasend.com/pricing).
</Tip>

<Info>
  **Account Owner Access:** Only the account owner can configure SSO and bypass it when necessary. Team members must use SSO once enabled.
</Info>

AhaSend SSO uses OpenID Connect (OIDC); SAML is not supported. Register `https://dash.ahasend.com/user/sso/oidc/callback` as the redirect URI in your identity provider.

## Configuration

Configure SSO in your account settings as the account owner:

<Steps>
  <Step title="Enable SSO" icon="toggle-on">
    **Navigate to SSO settings:**

    1. **Go to** **Account Settings** in your dashboard
    2. **Scroll to** **OpenID Connect SSO** section
    3. **Check** "Enable OpenID Connect SSO"
  </Step>

  <Step title="Configure Identity Provider" icon="gear">
    **Enter your IdP details:**

    **Required Configuration:**

    * **Configuration Type:** PKCE (recommended) or Client Credentials
    * **Domain:** Comma-separated email domains (e.g., `yourcompany.com`). You need to show that you own each one; see [Verify your SSO domains](#verify-your-sso-domains)
    * **Issuer URL:** Base URL from your IdP (e.g., `https://iam.company.com`)
    * **Client ID:** Provided by your identity provider
    * **Client Secret:** Required for the Client Credentials configuration; not required for PKCE. For PKCE, select `S256` as the PKCE method

    **Optional Settings:**

    * **Requested Scopes:** Space-separated scopes (defaults: `openid email profile`)
    * **Authorization Endpoint:** e.g., `https://iam.company.com/oauth/v2/authorize`
    * **Token Endpoint:** e.g., `https://iam.company.com/oauth/v2/token`
    * **Userinfo Endpoint:** e.g., `https://iam.company.com/oauth/v2/userinfo`
    * **JWKS URI:** e.g., `https://iam.company.com/oauth/v2/keys`
  </Step>

  <Step title="Validate and Activate" icon="check">
    **Complete SSO setup:**

    1. **Save** your configuration
    2. **System validates** the settings and checks that you own each new domain
    3. **SSO activates** if validation is successful
  </Step>
</Steps>

## Verify Your SSO Domains

SSO signs in people by their email address, so AhaSend only accepts sign-ins for addresses at your SSO domains, and you need to show that you own each domain when you first add it. Subdomains aren't included: if your team also uses `eu.yourcompany.com`, add it as its own domain. A domain counts as verified when either:

* **It is a verified sending domain** in the same AhaSend account. If you already send from `yourcompany.com`, there is nothing more to do. See [Domain setup](/docs/domains).
* **It has the SSO TXT record.** Use this for a domain you don't send from.

The TXT record is shown under the **Domain** field in your account settings:

| Type | Name | Value |
| - | - | - |
| `TXT` | `_ahasend-sso.yourcompany.com` | `ahasend-sso=...` (copy it from your settings page) |

The value is the same for every domain in your account, so you can add the record before you save. Replace `yourcompany.com` with each domain you add. See the [DNS provider guides](/docs/dns) for how to add a record.

AhaSend only checks a domain when you first add it. Once it is saved, you can remove the TXT record, and later changes to your DNS won't stop your team from signing in.

<Note>
  A domain can only be used for SSO by one AhaSend account. If another account already uses your domain, [contact support](mailto:support@ahasend.com).
</Note>

## How SSO Works

Once OpenID Connect SSO is activated:

**Team Member Access:**

* **Must use SSO:** All team members must sign in through your identity provider
* **No regular login:** Standard AhaSend login credentials are disabled
* **Access denied:** Password reset requests are blocked for team members

**Account Owner Access:**

* **SSO bypass:** Can still use regular AhaSend credentials
* **Password reset:** Can request password resets when needed
* **Full control:** Can disable SSO if necessary

<Warning>
  **Team Access:** Only users explicitly added as team members can access the account after SSO is enabled.
</Warning>

## Supported Identity Providers

<CardGroup cols={2}>
  <Card title="Microsoft Entra ID" icon="microsoft">
    **Azure Active Directory**

    Popular enterprise identity provider with comprehensive features
  </Card>

  <Card title="Google Workspace" icon="google">
    **Google Workspace identity provider**

    Integrated with Gmail and Google services
  </Card>

  <Card title="Okta" icon="shield-check">
    **Enterprise SSO Platform**

    Dedicated identity and access management
  </Card>

  <Card title="Self-Hosted Options" icon="server">
    **Authentik, Zitadel**

    Open-source identity providers you can host yourself
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Microsoft Entra ID Configuration" icon="microsoft">
    **Common setup issues:**

    * **Enable** "Allow public client flows" in app registration
    * **Set platform** to "Mobile and desktop applications" (not Web or Single-page)
    * **Verify** redirect URLs match AhaSend's requirements
  </Accordion>

  <Accordion title="Team Member Access Issues" icon="user-slash">
    **Login problems:**

    * **Verify** user is added as team member in AhaSend
    * **Check** the user's email address is at one of your SSO domains; sign-ins for other addresses are refused
    * **Check** your identity provider doesn't mark the user's email as unverified (`email_verified: false`); those sign-ins are refused
    * **Confirm** user exists in your identity provider
    * **Test** SSO configuration with account owner first
  </Accordion>

  <Accordion title="We Couldn't Verify a Domain" icon="globe">
    **Saving fails with "We couldn't verify ...":**

    * **Add** the domain as a sending domain and finish its DNS setup, or add the SSO TXT record
    * **Check** the record name is `_ahasend-sso.` followed by the domain, not the domain itself
    * **Copy** the value exactly from your settings page
    * **Wait** a few minutes after adding the record; DNS changes can take time to show up
  </Accordion>

  <Accordion title="Configuration Validation Errors" icon="triangle-exclamation">
    **Setup validation fails:**

    * **Double-check** all endpoint URLs are accessible
    * **Verify** client ID and secret are correct
    * **Ensure** identity provider is properly configured
    * **Test** JWKS URI returns valid JSON
  </Accordion>
</AccordionGroup>

## Related Guides

* [Account quickstart](/docs/quickstart), [Two-factor authentication](/docs/security/2fa), [Require team 2FA](/docs/security/2fa-enforcement).
* [Plans and limits](/docs/facts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.