canonical: https://jentic.com/apis/nhost.io/nhost

# Nhost API

Jentic publishes the only available OpenAPI specification for Nhost API, keeping it validated and agent-ready. Nhost is an open-source Firebase alternative that bundles authentication, GraphQL (Hasura), file storage, and serverless functions for app developers. This spec covers the Auth REST API: email and password sign-in, magic-link passwordless flows, personal access tokens, MFA TOTP enrolment, anonymous sessions, and user profile management. Each Nhost project runs in its own subdomain and region, so the base URL is templated with subdomain and region placeholders that resolve at request time.

## For AI agents

Sign users up, log them in, refresh tokens, and manage MFA on a Nhost backend through 16 REST endpoints under {subdomain}.auth.{region}.nhost.run/v1.

## Scope

Does not handle GraphQL queries, file storage, or serverless function invocation - use for Nhost authentication and user management only.

## Capabilities

- Register new users with email and password through `/signup/email-password`
- Issue magic-link passwordless sign-in emails through `/signin/passwordless/email`
- Authenticate users with personal access tokens through `/signin/pat`
- Enrol and activate TOTP multi-factor authentication on `/user/mfa` and `/user/mfa/totp`
- Refresh expired access tokens through /token without re-prompting the user
- Convert anonymous sessions into permanent accounts through `/user/deanonymize`
- Trigger password reset emails through `/user/password/reset`

## Use cases

### Email and password authentication for a Nhost app

Add full email and password authentication to a web or mobile app backed by Nhost. The Auth API handles user registration, sign-in, password hashing, refresh-token rotation, and password reset emails, so the application only needs to forward credentials and store the returned tokens. Sign-up and sign-in each return access and refresh tokens that can be used immediately against the GraphQL and Storage APIs on the same project.

Example prompt: Call POST `/signup/email-password` with email user@example.com and a password, then call POST `/signin/email-password` to confirm a session token is returned.

### Passwordless magic-link sign-in

Offer passwordless sign-in by emailing the user a one-time magic link. The `/signin/passwordless/email` endpoint accepts an email address and dispatches a link that, when clicked, completes the sign-in and returns a session. Useful for low-friction onboarding and for apps that do not want to manage user passwords at all.

Example prompt: Call POST `/signin/passwordless/email` with the user email so Nhost dispatches a magic-link sign-in email.

### TOTP multi-factor authentication enrolment

Add a second factor to user accounts using time-based one-time passwords. The agent calls POST `/user/mfa` to generate a TOTP secret and provisioning URI, displays a QR code for the user to scan into Google Authenticator or 1Password, then calls POST `/user/mfa/totp` with the user-supplied code to activate MFA on the account.

Example prompt: Call POST `/user/mfa` to generate a TOTP secret, then POST `/user/mfa/totp` with the six-digit code from the user's authenticator app to activate MFA.

### AI agent user onboarding flows

An AI agent embedded in a support or onboarding flow can register and authenticate users on a Nhost backend without the developer hand-coding requests. Through Jentic, the agent searches for the relevant Nhost auth operation by intent, loads the schema, and submits the credentials. Tokens are returned via Jentic's vault rather than ever entering the agent's chat context.

Example prompt: Search Jentic for 'sign up a user with email and password', load the Nhost POST `/signup/email-password` schema, and execute it with sample credentials.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/signup/email-password` | Sign up a new user with email and password |
| POST | `/signin/email-password` | Sign in an existing user with email and password |
| POST | `/signin/passwordless/email` | Send a magic-link sign-in email |
| POST | `/token` | Refresh an expired access token |
| POST | `/user/mfa` | Generate a TOTP secret for MFA enrolment |
| POST | `/user/mfa/totp` | Activate TOTP MFA after verifying a code |
| GET | `/user` | Get the current authenticated user |
| POST | `/signout` | Sign the user out and invalidate the refresh token |

## Key resources

- **Auth** — Sign-up, sign-in, sign-out, token refresh and passwordless flows
- **User** — Get profile, change email and password, manage password reset and email verification
- **MFA** — Enrol and activate TOTP-based multi-factor authentication

## Why Jentic

- **Setup:** Wiring Nhost auth by hand means handling its bearer tokens, resolving the per-project subdomain and region host (https://{subdomain}.auth.{region}.nhost.run/v1), and refreshing sessions yourself. Through Jentic you install once, import the Nhost API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Nhost auth routes its targets through the request body and session token rather than the URL path, so scope by operation: limit the agent to the operations it needs, such as email-password sign-in and reading the current user, and leave out sign-out or MFA changes unless you add them.
- **Credential handling:** Your Nhost token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'sign a user in with email and password' or 'fetch the current user', and Jentic returns the matching Nhost operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Supabase API** — Supabase is the most direct open-source Firebase alternative with auth, Postgres, and storage in one platform.
- **Auth0 Management API** — Auth0 is a hosted identity platform with broader social, enterprise, and SSO providers than Nhost Auth.
- **Clerk Backend API** — Clerk focuses on drop-in user management UIs and session handling for modern web apps.
- **Firebase API** — Firebase is the Google-hosted backend Nhost is positioned against, with auth, Firestore, and functions.

## FAQ

### Why is there no official OpenAPI spec for Nhost API?

Nhost does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Nhost API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Nhost API use?

The Nhost Auth API uses HTTP bearer tokens. Sign-in endpoints return an access token that callers send as Authorization: Bearer <token> on subsequent requests. Through Jentic, the bearer token is stored encrypted in the vault and never enters the agent's context.

### Can I enrol a user in MFA with the Nhost API?

Yes. Call POST `/user/mfa` to generate a TOTP secret and provisioning URI, present that to the user as a QR code, then call POST `/user/mfa/totp` with the six-digit code from their authenticator app to activate MFA on the account.

### What are the rate limits for the Nhost API?

Nhost does not publish public rate limits in this OpenAPI spec. Practical limits are governed per project on the Nhost backend; if requests are throttled, expect HTTP 429 responses with a Retry-After hint and back off accordingly.

### How do I sign up a user with the Nhost API through Jentic?

Run pip install jentic, then search Jentic for 'sign up a user with email and password'. Load the Nhost POST `/signup/email-password` schema and execute it with the email and password fields. Jentic returns the access and refresh tokens to your application.

### Is the Nhost API free to use?

Nhost offers a free tier for projects, with paid plans for larger workloads. The Auth API itself does not have separate per-call pricing - usage is included with your Nhost project plan. See nhost.io for current plan limits.

### Can I limit what my agent is allowed to do with the Nhost API?

Yes. Because you run Jentic One yourself, you decide which Nhost operations the agent may call and which credentials it may use. Since Nhost auth routes its target through the request body and session token rather than the URL path, you scope by operation: allow only what the agent needs, such as email-password sign-in on POST `/signin/email-password` and reading the current user on GET /user, while leaving out POST /signout or the MFA operations on POST `/user/mfa` and POST `/user/mfa/totp.` The stored bearer token is injected at execution time under those rules, so the agent can reach only the endpoints you permit.