# Bootstrap a tenant from a committed file Declare the machine clients, sign-in providers and first users your tenant needs in one JSON file. Commit it next to your code and review changes to it in pull requests. Then apply it to a fresh environment (a laptop, CI, a preview) with your tenant's own machine application, so every environment comes up the same way without anyone clicking through the dashboard. Applying a file only **creates**. It never changes or deletes anything. A record that already exists is reported `skipped` and left exactly as it is, whatever the file now says. To change a value later, use the dashboard or the Management API. For a disposable environment, start again from a new tenant. ## What a file can declare Each file covers one tenant that already exists: - **Machine clients:** `client_credentials` applications for your own services. Each new client's secret is generated by Udibo and shown once, in the response that created it. - **Sign-in providers:** Google, GitHub, Discord or Apple. - **Users:** people identified by email and username. Udibo emails each one a link to set their own password. No password or verified flag comes from the file. Some things a file cannot declare, because each needs a person to look at it: - **Applications people sign in to** (with redirect URIs). Register these in the dashboard. A redirect URI decides where sign-in codes are delivered, so it is never created by a machine credential. - **A generic OpenID Connect provider.** Add it in the dashboard. A provider whose issuer you choose could assert any email address, and social sign-in links verified addresses to existing accounts. - **Tenants, roles, permissions and tenant settings.** ## Set up the machine application once 1. In the dashboard, create an application with the **client credentials** grant. Give it the scopes the file needs: - `identity:applications:write` for clients; - `identity:providers:write` for providers; - `identity:users:write` for users. Also add every scope you want the clients it creates to hold. A new client can only receive scopes this application already has. 2. On that application's page, under **Machine permissions**, a tenant owner or administrator checks **Create machine applications**, **Create sign-in providers** and **Create users** as needed. A scope alone is not enough; each family also needs its permission. 3. Keep its client ID and secret in your secret store, as you would any production credential. Removing a permission or a scope takes effect on the application's next request. Records it already created stay in your tenant. Your audit log records each of them as created by this application. ## The file ```json { "clients": [ { "name": "Billing worker", "environment": "production", "scopes": ["identity:organizations:read"] } ], "identityProviders": [ { "type": "google", "clientId": "1234.apps.googleusercontent.com", "clientSecret": { "env": "GOOGLE_CLIENT_SECRET" }, "enabled": true } ], "users": [{ "email": "ada@example.com", "username": "ada", "firstName": "Ada" }] } ``` - **Secrets are environment references,** written `{ "env": "NAME" }`. A literal value is refused, so the file is safe to commit. - **Every object is closed.** An unknown or misspelled field is refused by its path (`users[0].password: unknown field`), never ignored. - **How an existing record is recognized:** a client by `name`, a provider by `type`, a user by `email` or `username`. - **An enabled provider** appears on every sign-in page in your tenant as soon as it is created. Leave `enabled` out, or set it to `false`, to turn it on later in the dashboard. ## Apply it over the API Get a token with your machine application's credentials at your tenant's token endpoint. Then send one `POST` per record to your tenant's own origin: ```bash curl -s -X POST https://acme.udibo.com/api/oauth2/token \ -u "$UDIBO_CLIENT_ID:$UDIBO_CLIENT_SECRET" \ -d grant_type=client_credentials \ -d scope="identity:applications:write identity:providers:write identity:users:write" ``` | Record | Request | Created answer | | -------- | -------------------------------------- | -------------------------------------------- | | Client | `POST /api/machine/applications` | `201` with `application` and its `secret` | | Provider | `POST /api/machine/identity-providers` | `201` with the provider (its secret omitted) | | User | `POST /api/machine/users` | `201` with the user | A record that already exists answers `409` with `reason: "already_exists"`. For a client or provider, the answer also carries its `id`. A user's `409` carries no id, because creating users does not grant a read of your user directory. Treat any `409 already_exists` as "skipped" and carry on. The [API reference](https://www.udibo.com/docs/api) lists each request's exact fields. ### Limits - **Creates per application per hour:** 60 clients, 20 providers and 600 users. Every attempt counts, a `409` included. - **Account emails per application per day:** 1,000. Past this cap a user create answers `429` with `reason: "email_cap"`, and **no user is created**. - **Repeated mail to one address:** with password sign-in on, if that address has had too many account emails recently, the create answers `429` and no user is created. Each `429` carries `Retry-After`. Your tenant's own monthly and daily email limits also apply. ## What a created user receives The person gets your tenant's password-reset email, which lets them set a first password. Following the link proves they hold the mailbox and verifies the address. If your tenant has password sign-in turned off, they get the verification email instead and sign in with a method you offer. Until they follow the link, the account has no way to sign in. Signing in with Google using the same address is refused rather than linked, because the account's email is not verified yet. The person can use your tenant's **Forgot password** page to get a new link at any time. ## Applying the same file again Run it on every deploy if you like. Records already present are skipped, so a second run creates nothing new. Deleting a record in the dashboard while it is still in the file means the next run creates it again, empty, so remove it from the file as well. _Last verified 2026-11-19._