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_credentialsapplications 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
In the dashboard, create an application with the client credentials grant. Give it the scopes the file needs:
identity:applications:writefor clients;identity:providers:writefor providers;identity:users:writefor users.
Also add every scope you want the clients it creates to hold. A new client can only receive scopes this application already has.
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.
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
{
"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 bytype, a user byemailorusername.An enabled provider appears on every sign-in page in your tenant as soon as it is created. Leave
enabledout, or set it tofalse, 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:
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 lists each request's exact fields.
Limits
Creates per application per hour: 60 clients, 20 providers and 600 users. Every attempt counts, a
409included.Account emails per application per day: 1,000. Past this cap a user create answers
429withreason: "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
429and 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.

