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

# Manage workspace identity and user provisioning

> Verify your email domain, connect single sign-on, and control how people from your company join the workspace.

The **Identity** page in workspace settings is where owners and admins control how your team signs in to Vibely and how they join the workspace. It brings together domain verification, single sign-on (SSO), requiring SSO, and automatic user provisioning.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/features-workspace-identity.webp" alt="Verify your domain, then connect SSO" width="1200" height="675" />
</Frame>

* **Available on:** Business
* **Access:** workspace owners and admins
* **Location:** **Settings → Access → Identity** (`vibely.sh/settings/identity`). The same SSO and SCIM controls also appear in **Settings → Security center**.

<Note>
  This page is about how your team signs in to **Vibely itself**. To add sign-in to an app you build, see [Authentication](/features/backend/auth).
</Note>

## What's on the Identity page

| Section | What it does | Details |
| - | - | - |
| **Domain verification** | Proves your company owns its email domain. Required for everything below. | [Verify your domain](#verify-your-domain) |
| **Single sign-on** | Connects one SAML 2.0 or OIDC identity provider, such as Okta, Microsoft Entra ID, or Auth0. | [SSO](/features/workspace/sso) |
| **Require SSO** | Makes your identity provider the only way to join the workspace and to sign in as a member. | [Require SSO](#require-sso-and-session-duration) |
| **User provisioning** | Sets the role people get when they join automatically, and issues the SCIM token. | [User provisioning](#user-provisioning), [SCIM](/features/workspace/scim) |

## Verify your domain

Verifying a domain proves your company owns it. Nothing else on the Identity page works until it's verified, and verification is what stops another workspace from claiming a domain like `gmail.com`.

### Before you start

* A Business workspace, and the owner or admin role in it.
* Access to your domain's DNS settings, or someone who can add a record for you.

### Verify a domain

<Steps>
  <Step title="Enter your email domain">
    Under **Domain verification**, enter the domain your team's email addresses end in, for example `acme.com` (not `@acme.com` and not a URL), and click **Save**.
  </Step>

  <Step title="Copy the DNS record">
    Vibely shows a TXT record:

    | Field | Value |
    | - | - |
    | Type | `TXT` |
    | Name | `_vibely-verify.acme.com` |
    | Value | `vibely-domain-verification=<token>` |
  </Step>

  <Step title="Add the record at your DNS provider">
    If your provider adds the domain for you (the name field already shows `.acme.com`), enter just `_vibely-verify`.
  </Step>

  <Step title="Click Verify">
    Vibely looks up the record and compares it with the one it gave you. The status changes from **Pending** to **Verified**. DNS changes can take a few minutes to propagate; if the check fails, wait and try again.
  </Step>
</Steps>

<Warning>
  The record goes on the `_vibely-verify` subdomain, **not** on the root (`@`). This is the most common reason verification fails.
</Warning>

### How domain verification works

* A workspace verifies **one** email domain.
* A domain can belong to only one workspace. If another workspace already claimed it, saving it fails with "already linked to another workspace".
* Changing the domain clears its verification. You get a new record and have to verify again.

### Troubleshooting verification

| Problem | Fix |
| - | - |
| **Verify** keeps failing | Check the record is on `_vibely-verify`, not `@`, and that the value includes the `vibely-domain-verification=` prefix. |
| "Already linked to another workspace" | Another workspace verified this domain. Ask its owner to remove it, or contact support. |
| It worked, then SSO stopped | The domain was changed, which cleared verification. Verify again. |

## User provisioning

Once your domain is verified and SSO is on, people from your company can join the workspace without an invitation.

### Role on first SSO login

When someone with an email on your verified domain signs in and isn't a member yet, Vibely adds them to the workspace with the role you choose here: **Viewer**, **Editor**, or **Admin**. It defaults to **Editor**, which can create and publish projects, so set it deliberately.

This happens on any successful sign-in by an address on your domain, not only sign-ins through your identity provider, unless you [require SSO](#require-sso-and-session-duration).

If the person's default workspace is a free one they own, Vibely also makes your workspace their default, so they land in the company workspace instead of their personal one. A paid personal workspace is never touched.

### SCIM provisioning

Your identity provider can create, update, and remove members for you. Issue a SCIM token here and set the **Role for SCIM users**. See [SCIM](/features/workspace/scim).

### How provisioning methods interact

| Path | When it fires | Role given |
| - | - | - |
| **Sign-in** | Someone on your verified domain signs in and isn't a member | **Role on first SSO login** |
| **Invitation** | An owner or admin invites an address | The role on the invitation |
| **SCIM** | Your identity provider pushes a user | **Role for SCIM users** |

Provisioned members are managed like everyone else: they appear in [People](/features/workspace/people), where you can change their role or remove them.

## Require SSO and session duration

With a verified domain and SSO enabled, you choose how strict sign-in is:

| Setting | Effect |
| - | - |
| **Enable SSO** | People who enter an email on your domain at sign-in are sent to your identity provider. |
| **Require SSO** | Your identity provider becomes the only way to join and to use Vibely as a member. Invitations and external collaborators are turned off, only sign-ins that came through your identity provider add new members, and members who signed in any other way are signed out. |

You can only require SSO once the domain is verified; otherwise the workspace could lock itself out.

### How Require SSO is enforced

Vibely checks every request from a member of an SSO-enabled Business workspace. If **Require SSO** is on and the member's session didn't come through your identity provider (for example, they signed in with a password or with Google), Vibely signs them out and sends them to the sign-in page with the message "Your workspace requires single sign-on." They sign in again with their work email to go through your identity provider.

* **The workspace owner is exempt**, so they can always get back in to fix the SSO setup if the identity provider breaks.
* **It applies to all of the member's Vibely usage**, not just this workspace. A member who also belongs to other workspaces has to sign in through SSO to use any of them.

<Warning>
  Requiring SSO turns off invitations for the whole workspace, with no per-person exceptions. Plan how you'll work with contractors and other outside collaborators before you turn it on.
</Warning>

### Session duration

**Session duration** offers 24 hours, 48 hours, or 7 days (the default). It sets how long an SSO sign-in lasts. When a member's SSO session is older than the setting, Vibely signs them out with the message "Your single sign-on session has expired", and they sign in again through your identity provider.

Changes to **Require SSO** and **Session duration** take effect within about a minute.

## FAQ

<AccordionGroup>
  <Accordion title="Can I verify more than one domain?">
    No. Each workspace verifies one email domain.
  </Accordion>

  <Accordion title="Nobody is being added automatically. Why?">
    Automatic joining needs the domain verified **and** SSO enabled on a Business workspace. If SSO is required, the sign-in also has to come through your identity provider.
  </Accordion>

  <Accordion title="SSO sign-in falls back to a password prompt.">
    A domain only routes to SSO when all of these are true: SSO is enabled, the domain is verified, the workspace is on Business, and every field the chosen protocol needs is filled in. See [SSO troubleshooting](/features/workspace/sso#troubleshooting).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="SSO" icon="key" href="/features/workspace/sso">
    Connect Okta, Entra ID, Auth0, or any SAML 2.0 or OIDC provider.
  </Card>

  <Card title="SCIM" icon="arrows-rotate" href="/features/workspace/scim">
    Provision and deprovision members from your identity provider.
  </Card>

  <Card title="People" icon="users" href="/features/workspace/people">
    Manage members after they join.
  </Card>

  <Card title="Privacy & security" icon="lock" href="/features/workspace/privacy-security">
    Restrict invitations to your company's domains.
  </Card>
</CardGroup>


## Related topics

- [Manage workspace members from the People page](/features/workspace/people.md)
- [Set up SCIM user provisioning](/features/workspace/scim.md)
- [Vibely for Enterprise](/introduction/enterprise.md)
- [Set up workspace single sign-on (SSO)](/features/workspace/sso.md)
- [Workspace security center](/features/workspace/security-center.md)


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