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

# Single sign-on and one-time codes

> Sign in with your identity provider over SAML, or with an emailed one-time code — and the provisioning rule that surprises every first SSO rollout.

Beyond a password, aiAxonIQ supports **SAML single sign-on** against your
identity provider, and **one-time codes** sent by email.

<Info>
  **This is about signing in to the product.** Sending telemetry uses a license
  key and is unrelated — the two credentials are not interchangeable. See
  [Authentication](/get-started/authentication).
</Info>

## SAML single sign-on

Your identity provider authenticates the user; aiAxonIQ issues the session.

<Steps>
  <Step title="Fetch the service provider metadata">
    `GET /auth/saml/metadata` returns what your identity provider needs to
    register aiAxonIQ as a service provider.
  </Step>

  <Step title="Configure the application in your identity provider">
    Any SAML 2.0 provider — Okta, Entra ID, Google Workspace, Ping, OneLogin.
    The user's email address is the identifier that must match.
  </Step>

  <Step title="Check it is enabled">
    `GET /auth/saml/status` reports whether SSO is configured for the
    deployment, which is what a sign-in page uses to decide whether to offer
    the button.
  </Step>

  <Step title="Sign in">
    `GET /auth/saml/login` starts the flow. Your provider authenticates, posts
    an assertion back, and the resulting short-lived token is exchanged for an
    ordinary session.
  </Step>
</Steps>

### The rule that surprises every first rollout

<Warning>
  **Your identity provider asserts *identity only*. It does not create
  accounts, and it does not set roles.**

  An authenticated user with no existing aiAxonIQ membership is refused with
  `403` — not provisioned on the fly. Role and organization come from the local
  membership, every time.

  So the sequence is: **invite the user first, then have them sign in with
  SSO.** A rollout that enables SSO and tells everyone to log in will produce a
  wave of `403`s from people whose authentication worked perfectly.
</Warning>

This is deliberate. Just-in-time provisioning means whoever controls the
identity provider's group membership silently controls who can read your
telemetry — and a group misconfiguration becomes a data-access incident with no
step in between. Keeping membership local means adding someone to aiAxonIQ is
always an explicit act, recorded in your [audit log](/guides/audit).

<Note>
  **Roles are managed in aiAxonIQ, not mapped from SAML attributes.** Change
  someone's role in **Settings → Users**. See
  [Roles and permissions](/concepts/roles).
</Note>

## One-time email codes

A code sent to your email address, exchanged for a session — useful where you
do not want passwords and do not have SAML.

Two behaviours are worth knowing because they look like bugs:

<Note>
  **Requesting a code always answers success**, with the same body, whether or
  not the address belongs to an account. That is what stops the endpoint being
  used to discover who has an account. A code is only actually sent if the
  address could sign in.

  **Every code failure answers identically.** Wrong code, expired code and
  already-used code are indistinguishable from outside, for the same reason.
  If a code is not working, request a fresh one rather than trying to interpret
  the error.
</Note>

<Warning>
  **One-time codes depend on email delivery being configured for your
  deployment.** So do invitations, email verification and password resets. If
  no code arrives and no error appears, that is the thing to check with your
  operator or account contact before debugging anything else.
</Warning>

## Sessions

|                         |                                                        |
| :---------------------- | :----------------------------------------------------- |
| **Browser**             | An HttpOnly cookie set at sign-in                      |
| **Programmatic**        | `Authorization: Bearer <token>`                        |
| **Refresh**             | Sessions refresh rather than requiring a fresh sign-in |
| **Sign out everywhere** | Revokes every session for your account                 |

<Note>
  **Signing out everywhere is genuinely everywhere.** It advances a counter
  that invalidates previously-issued tokens, so a token that had been captured
  stops working even though nothing about it changed. This is the action to
  take if you think a session has been compromised.
</Note>

## Switching organizations

If you belong to more than one organization, switching **mints a new session**
rather than editing the current one — so a token captured while you were in one
organization cannot follow you into another.

Your role is per organization: Owner in one and Viewer in another is normal.
See [Organizations and multi-tenancy](/concepts/organizations).

## Next

<CardGroup cols={3}>
  <Card title="Authentication" icon="shield-halved" href="/get-started/authentication">
    The two credentials and which to use where.
  </Card>

  <Card title="Roles and permissions" icon="user-shield" href="/concepts/roles">
    What each role can do, and who may grant it.
  </Card>

  <Card title="Enterprise onboarding" icon="building-columns" href="/onboarding/enterprise">
    Rolling this out across many teams.
  </Card>
</CardGroup>