Tenant Onboarding

This guide walks through provisioning an organization in Curupira — creating your tenant, its first application, and the redirect URIs and credentials your app needs to sign users in.

For the full endpoint reference see the Admin API; to wire the login flow into your app afterwards see Add login to your app.

Concepts

Term	What it is
Tenant	Your organization — the top-level container for applications, users, roles, and SSO connections. Identified by a URL-safe slug (e.g. acme) and a display name.
Application	An OAuth2/OIDC client within a tenant (a web app, SPA, mobile app, or service). Each has a client ID, an API key, and a set of redirect URIs.
Redirect URI	The exact URL Curupira sends the user back to after login. It must be pre-registered — the authorization request is rejected if redirect_uri doesn't match one on file.

:::info A tenant always has at least one application A tenant is created together with its first application — you can't have an empty tenant. Add more applications later as needed. :::

1 · Create your tenant and first application

Option A — Admin dashboard

1. Sign in to the admin dashboard.
2. Go to Tenants → Create.
3. Fill in:
   • Slug — a short, URL-safe identifier (lowercase, e.g. acme). Used in login URLs.
   • Name — the organization's display name.
   • Application name — your first app (e.g. Acme Web).
   • Redirect URIs — one per line (see rules below).
4. Create. The tenant and its first application are provisioned together, and the app's client ID and API key are shown.

:::warning Copy the API key now The application API key is shown once, at creation. Store it securely — it can't be retrieved later, only rotated. :::

Option B — Admin API

Provision the same thing with a single call:

curl -X POST https://auth.curupira.api.br/api/admin/tenants \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{
    "slug": "acme",
    "name": "ACME Corp",
    "initial_app": {
      "name": "Acme Web",
      "redirect_uris": ["https://app.acme.example/callback"],
      "post_logout_redirect_uris": ["https://app.acme.example/"]
    }
  }'

initial_app is required (a tenant must have at least one application). The response includes the new application's client ID and API key — capture both.

Admin endpoints authenticate with an admin session and enforce per-tenant permissions; see the Admin API for authentication and the full endpoint list.

2 · Redirect URIs

Redirect URIs are validated on create and update:

• At least one redirect URI is required per application.
• Each must start with http:// or https:// — use https:// in production; http:// is for local development (e.g. http://localhost:3000/callback).
• Curupira matches the request's redirect_uri against the registered list exactly, so register every callback URL you use (path and all).
• Post-logout redirect URIs are optional — the URLs Curupira may return to after sign-out.

3 · Add more applications

A tenant can hold many applications (one per app/service). Create additional ones with:

curl -X POST https://auth.curupira.api.br/api/admin/applications \
  -H 'Content-Type: application/json' -b cookies.txt \
  -d '{
    "tenant_id": "<your-tenant-uuid>",
    "name": "Acme Mobile",
    "redirect_uris": ["com.acme.app://callback"],
    "post_logout_redirect_uris": []
  }'

or in the dashboard under Applications → Create. You can update an application's redirect URIs and settings at any time (PUT /api/admin/applications/{id}).

4 · Rotate an API key

Rotate an application's API key when it may be compromised, or on a regular schedule:

curl -X POST https://auth.curupira.api.br/api/admin/applications/{id}/regenerate-apikey \
  -b cookies.txt

The new key is returned once. Rotation immediately invalidates the previous key, so update your app's configuration promptly.

Next steps

• Add login to your app — wire the OAuth2/OIDC flow using your new client ID and redirect URI.
• SSO Provider Setup — let your users sign in with Google, Microsoft, GitHub, and more.
• Roles & permissions — model what your users can do (RBAC management guide, coming soon).