> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/account-management/creating-an-account.md).

# Creating an Account

Self-serve signup is open to anyone. Two calls take someone from nothing to a verified account.

{% hint style="info" %}
These endpoints serve Duro's own web app. They accept requests only from Duro's own web origin (`https://durohub.com`), which is why the examples send that `Origin` header — a browser app on any other origin gets `403 AUTH_ORIGIN_REJECTED`. They are documented so you know how accounts come to exist, not as an integration surface: integrations use an [API key](https://docs.durohub.com/getting-started/authentication.md), and identity providers use [SSO](https://docs.durohub.com/account-management/enterprise-sso.md) and [SCIM](https://docs.durohub.com/account-management/scim-provisioning.md).
{% endhint %}

```
POST /auth/signup ──► 202
        │
        ▼
   verification email ──► https://durohub.com/verify-email?token=…
        │
        ▼
POST /auth/verify-email ──► 200, address verified
```

## Step 1 — Register

```bash
curl -sX POST https://api.durohub.com/auth/signup \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://durohub.com' \
  -d '{
        "email": "dana@acme.com",
        "name": "Dana Reyes",
        "password": "Correct-Horse-Battery-9!"
      }'
```

```json
{ "status": "pending_verification" }
```

{% hint style="info" %}
Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).
{% endhint %}

`202 Accepted` — signup creates an identity and stops there.

| Field      | Required | Notes                                                                                                                                             |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`    | Yes      | Max 254 characters, and must look like an address (`name@domain.tld`). Otherwise `400 AUTH_REQUEST_REJECTED`, "A valid email address is required" |
| `password` | Yes      | Must satisfy the live policy — see [Password rules](#password-rules)                                                                              |
| `name`     | No       | Derived from the address when omitted                                                                                                             |

### Every signup returns the same 202

Register an address that already has an account and you get the same status and the same body. Nothing is created and no existing account is touched. Duro emails the address's owner instead, letting them know someone tried to sign up and offering a password reset.

{% hint style="info" %}
**Do not render "that email is already taken."** The response cannot tell you, because a distinguishable answer would let anyone test a list of addresses to learn who has a Duro account.

Show the same "check your email" state for every accepted signup and let the mailbox resolve it.
{% endhint %}

A malformed address or a rejected password is the exception — those come back as a `400`, since they describe what the caller just typed rather than who exists. See [Password rules](#password-rules) for what the password `400` says.

## Password rules

The rules are served at runtime rather than fixed, so fetch them instead of hardcoding:

```bash
curl -s https://api.durohub.com/auth/config
```

```json
{
  "nativeAuthEnabled": true,
  "passwordPolicy": {
    "mode": "duro",
    "minLength": 12,
    "maxLength": 256,
    "requireClasses": true
  },
  "googleSignIn": true
}
```

`passwordPolicy` is the part that matters for a signup form. `googleSignIn` says whether Sign in with Google is offered on this host.

|                                                        | `duro` | `nist` |
| ------------------------------------------------------ | ------ | ------ |
| Minimum length                                         | 12     | 15     |
| Maximum length                                         | 256    | 256    |
| Lowercase, uppercase, number, and symbol each required | Yes    | No     |
| Common-pattern check                                   | Yes    | Yes    |
| Passwords found in known data breaches rejected        | Yes    | Yes    |

Which mode is active is a deployment setting — read `passwordPolicy.mode` rather than assuming. `nist` follows NIST SP 800-63B, which asks for more length and no character-class requirements.

Two things worth knowing if you validate before submitting:

* **Symbols are anything that is not a letter, a digit, or whitespace** — not a fixed `!@#$%^&*` list, so `£`, `€`, and non-Latin symbols all count
* **Common patterns are rejected** — a capitalised word followed by digits and punctuation (`Password1!`, `Summer2026!`), keyboard runs like `qwerty`, and long character repeats

A rejected password returns `400 AUTH_REQUEST_REJECTED`. The message names the rule only for length ("Password must be at least 12 characters") and for a breached password ("That password has appeared in a data breach. Choose a different one"). A missing character class or a common pattern returns the same "Choose a different password" for every case, so evaluate those rules from `/auth/config` in your form rather than parsing the message.

{% hint style="info" %}
The endpoint is unauthenticated and cheap, so call it before rendering a signup form and show the live rules. A form that says "at least 12 characters" against a server enforcing 15 accepts the password and then fails on submit with nothing explaining why.
{% endhint %}

## Step 2 — Verify the email address

The email links to the Duro app, not the API:

```
https://durohub.com/verify-email?token=<token>
```

That page posts the token:

```bash
curl -sX POST https://api.durohub.com/auth/verify-email \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://durohub.com' \
  -d '{"token":"<token>"}'
```

```json
{ "status": "verified" }
```

Tokens are single-use and expire after **one hour**. Unknown, expired, already-used, and wrong-purpose tokens all return:

```json
{ "code": "AUTH_TOKEN_INVALID", "message": "This link is invalid or has expired" }
```

Give that case somewhere to go — a "request a new link" action and a route back to sign-in. A link that sat in an inbox overnight is the common case, not the edge case.

## Verification is required

An address must be verified before Duro will apply an invitation, an allowlist entry, or a domain match to it. Until then the account exists but cannot join anything.

Verification comes from one of three places:

* **Password accounts** — consuming the emailed token
* **Google** — Google asserting the address is verified
* **SAML** — an organization asserting an address inside a domain it has [verified ownership of](https://docs.durohub.com/account-management/enterprise-sso.md#step-1-verify-your-domain)

Completing a password reset also counts, since it proves the same thing.

## What a new account can do

Very little until something admits it. Duro lets someone in when any of these is true:

| Route in                | How it happens                                                 |
| ----------------------- | -------------------------------------------------------------- |
| **Existing membership** | They already belong to an organization                         |
| **Invitation**          | An admin invited their address, and they verified it           |
| **Allowlist**           | An organization's allowlist covers their address or its domain |
| **Org-creation grant**  | Duro issued a pending grant to create a new organization       |

With none of those, organization-scoped queries are refused. `user { me { permitted } }` tells you which state you are in: it is true when any route above applies. (`hasOrganizations` is narrower — it is false for someone admitted by an invitation, allowlist, or grant who does not belong to an organization yet.) See [Current User](https://docs.durohub.com/getting-started/current-user.md).

{% hint style="info" %}
If people are meant to arrive by invitation, **send the invitation first**, to the exact address they will verify. Invitations match the verified address ignoring case, so `Dana@Acme.com` matches `dana@acme.com` — but an invitation to `dana@acme.com` does not admit an account that verified `dana.reyes@acme.com`. It stays open, unused.
{% endhint %}

## Rate limits

| Route                     | Limit, per IP address |
| ------------------------- | --------------------- |
| `POST /auth/signup`       | 100 per 10 minutes    |
| `POST /auth/verify-email` | 200 per 10 minutes    |

Both routes count per IP address and never per account, so nobody can lock an address out by hammering it, and the limits are high enough for an office signing people up from one address. Each window starts at the first attempt.

Past the limit, requests slow down rather than failing outright: each further attempt waits half a second longer, up to five seconds. A `429 AUTH_RATE_LIMITED` only appears once attempts past the limit exceed ten times the limit — the 1,101st signup from one address in a window. The refusal carries the wait in seconds, as `retryAfter` in the body and as a `Retry-After` header:

```json
{ "code": "AUTH_RATE_LIMITED", "message": "Too many attempts. Wait a moment and try again", "retryAfter": 600 }
```

Signing in and password reset are limited differently — per account from each IP address — and the GraphQL API has its own per-user and per-key budgets. See [Rate Limits](https://docs.durohub.com/rate-limits/rate-limits.md).

## Errors

| Code                    | Status | Means                                                                |
| ----------------------- | ------ | -------------------------------------------------------------------- |
| `AUTH_ORIGIN_REJECTED`  | 403    | Missing or non-allowlisted `Origin` header                           |
| `AUTH_TOKEN_INVALID`    | 400    | Verification token unknown, expired, or already used                 |
| `AUTH_RATE_LIMITED`     | 429    | Far past the route's limit; wait `retryAfter` seconds                |
| `AUTH_REQUEST_REJECTED` | 400    | Malformed request or email address, or a password the policy refused |
| `AUTH_UNAVAILABLE`      | 503    | Duro could not complete the request; try again                       |

Every `/auth/*` error returns this flat shape — `AUTH_RATE_LIMITED` adds `retryAfter`, as shown under [Rate limits](#rate-limits). Branch on `code`; the `message` is copy and may be reworded.

```json
{ "code": "AUTH_TOKEN_INVALID", "message": "This link is invalid or has expired" }
```

## Next steps

Once accounts exist, [Enterprise SSO](https://docs.durohub.com/account-management/enterprise-sso.md) lets your identity provider sign those people in, and [SCIM Provisioning](https://docs.durohub.com/account-management/scim-provisioning.md) creates and deprovisions them from your directory automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/account-management/creating-an-account.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
