Skip to content
Udibo

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:

Shell
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"
RecordRequestCreated answer
ClientPOST /api/machine/applications201 with application and its secret
ProviderPOST /api/machine/identity-providers201 with the provider (its secret omitted)
UserPOST /api/machine/users201 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 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.

View Markdown