---
title: "Enable a directory"
description: "Create your organization's directory, choose its alias and portal URL, and set its sign-in policy and branding."
---

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

# Enable a directory

Enabling EZGH SSO creates your organization's directory. An organization has at most one. You
need `sso.directories.create` (in `SsoFullAccess`).

## Create the directory

### Console

Open **EZGH SSO** and select **Enable**. Enter a name and an alias.
### CLI

```sh
ezgh sso directory create --name "Acme" --alias acme
ezgh sso directory get
```
### API

Call [CreateDirectory](/sso-api/CreateDirectory/) with `name` and `alias`, and optionally
`signInPolicy`, `branding` and `tags`.

```sh
curl -X POST https://sso.ezghcloud.com/v1/organizations/$ORG_ID/sso/directory \
  -H "Authorization: Bearer $EZGH_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "alias": "acme" }'
```

The answer includes the directory's `portalUrl` and `issuer`, both `https://acme.sso.ezgh.app`.
[GetDirectory](/sso-api/GetDirectory/) returns it; without a directory it's `404`.

## Directory fields

| Field | Description |
| --- | --- |
| `id`, `slug`, `resourceName` | The directory's ID (a UUID), slug (`dir_…`) and resource name, `ezgh:us-west-1:org_…:dir_…`. |
| `name` | 1 to 100 characters, without control characters. |
| `alias` | The portal's host name: `https://<alias>.sso.ezgh.app`. See [Aliases](#aliases). |
| `portalUrl`, `issuer` | `https://<alias>.sso.ezgh.app`: where people sign in, and the OIDC issuer. |
| `signInPolicy` | See [Sign-in policy](#sign-in-policy). |
| `branding` | See [Branding](#branding). |
| `tags` | Up to 50 key-value pairs. Keys are 1 to 128 characters and can't start with `ezgh:`; values are up to 256 characters. |
| `status` | `active`. |
| `region` | `us-west-1`. |

## Aliases

An alias is 4 to 32 characters: lowercase letters, digits and hyphens, starting with a letter and
not ending with a hyphen (`^[a-z][a-z0-9-]{2,30}[a-z0-9]$`). Platform words (such as `www`,
`api`, `admin`, `login`, `auth` and `ezgh`) and names that imitate brands are reserved. An alias
in use, or used before, by any directory is refused.

You can change the alias with [UpdateDirectory](/sso-api/UpdateDirectory/). The portal and
issuer move to the new host at once. The old host redirects to the new one for 30 days, and the
old alias is never used again. Because the issuer changes, update your applications'
configuration (issuer, discovery URL and endpoints) when you change the alias. The same goes for
SAML applications' IdP URLs and your identity providers' redirect URI, ACS URL and entity ID.

> **Caution**
>
> Passkeys belong to the host they were created on. After an alias change, passkeys created on the
> old host no longer sign in: users sign in with a password and TOTP if the policy allows them, or
> you [reset their factors](/sso/users#statuses) so they can create new passkeys.

## Sign-in policy

The policy applies to everyone in the directory, on every request.

| Field | Description | Default |
| --- | --- | --- |
| `mfaRequired` | Hosted users must use two factors: a passkey, or a password and a TOTP code. | `true` |
| `allowedFactors` | 1 to 3 of `password`, `totp` and `passkey`. With `mfaRequired`, it must include `passkey`, or both `password` and `totp`. | All three |
| `sessionDurationSeconds` | How long a portal session lasts from sign-in: 300 to 86,400 (24 hours). | 28,800 (8 hours) |
| `idleTimeoutSeconds` | How long a session lasts without use: 60 to `sessionDurationSeconds`. | 3,600 (1 hour) |
| `trustUpstreamMfa` | Accept an identity provider's evidence of MFA. See [MFA and identity providers](/sso/identity-providers#mfa). | `false` |

`signInPolicy` is replaced whole: send every field. A field you leave out takes its default, not
its current value. (`ezgh sso directory update` reads the current policy and sends it with your
changes.) A shorter session length or idle timeout applies to existing sessions at once.

```sh
ezgh sso directory update --session-duration 4h --idle-timeout 30m
```

## Branding

The portal and sign-in pages show your logo and two colors. Your directory can't add its own
HTML, CSS or scripts.

| Field | Description | Default |
| --- | --- | --- |
| `primaryColor` | `#RRGGBB`. Buttons and links. | `#2563eb` |
| `backgroundColor` | `#RRGGBB`. The page background. A readable text color is chosen for each. | `#ffffff` |
| `logoUrl` | Read-only: where the uploaded logo is served, `https://<alias>.sso.ezgh.app/branding/logo`, or `null`. | `null` |

Like the policy, `branding` is replaced whole. `logoUrl` can be left out, or sent back unchanged.

Upload a logo with [UpdateDirectoryLogo](/sso-api/UpdateDirectoryLogo/): `{ "data": "<base64>" }`,
a PNG or JPEG of at most 512 KiB and 1024 × 1024 pixels. It's converted to a PNG. SVG files and
links to images elsewhere are refused. [DeleteDirectoryLogo](/sso-api/DeleteDirectoryLogo/)
removes it. Each application's portal tile can have its own logo too: see
[Tile logo](/sso/applications#tile-logo).

## Delete the directory

[DeleteDirectory](/sso-api/DeleteDirectory/) (`ezgh sso directory delete`) removes the
directory and everything in it, at once: every user and group with their sessions and factors,
its email domains, custom domains, identity providers, SCIM tokens, applications with their
secrets, assignments, provisioning settings and tokens, its signing keys and SAML certificates,
and the logo. Applications stop being able to sign anyone in, and nobody is deprovisioned at
applications that EZGH SSO provisions. The alias is never used again. This can't be undone.

Source: https://docs.ezghcloud.com/sso/directory/index.mdx