Skip to main content

Admin API Guide

The Admin API is how tenants, applications, users, roles, role groups, and logs are managed programmatically. It is the same API the admin dashboard uses. This page is an overview and orientation — the exhaustive, always-accurate endpoint reference is generated from the OpenAPI spec (see API Reference).

:::note Reference vs. guide This guide explains the shape and auth of the admin surface so you can find your way around. The field-by-field, endpoint-by-endpoint contract lives in the machine-readable OpenAPI document, which is the source of truth. See the API Reference page. :::

Base URL & authentication​

Admin endpoints live under /api/admin/... on the auth host and authenticate with a session cookie established by logging in as an admin user (the dashboard does this for you). Access is governed by the admin RBAC layer — an admin user holds an admin role (e.g. super_admin) scoped to a tenant, and each handler enforces the required permission.

Base:  https://auth.curupira.api.br/api/admin
Auth:  session cookie (admin login) + admin-role permission checks

Every state-changing admin action is recorded in the audit log (who did what, with old vs. new values), so administration is fully traceable.

What you can manage​

The admin surface mirrors the product model:

Tenants​

  • GET /api/admin/tenants — list tenants (paginated).
  • POST /api/admin/tenants — create a tenant with its initial application (a tenant is never created empty).
  • GET /api/admin/tenants/{id} — tenant detail + stats.

Applications​

  • GET /api/admin/applications — list (filterable by tenant).
  • POST /api/admin/applications — create an application.
  • GET /api/admin/applications/{id} — detail.
  • PATCH/PUT /api/admin/applications/{id} — update (e.g. redirect URIs, roles, enabled).
  • POST /api/admin/applications/{id}/regenerate-apikey — rotate the API key (invalidates the old one).

Roles & role groups​

  • GET|POST /api/admin/roles, GET /api/admin/roles/{id}, update/delete — manage roles (each role belongs to an application).
  • GET|POST /api/admin/role-groups, GET /api/admin/role-groups/{id}, delete — manage role groups and their member roles (.../role-groups/{group_id}/roles/{role_id} to add/remove a member).

Users & their permissions​

  • GET /api/admin/users, GET /api/admin/users/{id} — list / detail.
  • Assign or remove roles and role groups for a user (.../users/{id}/roles, .../users/{id}/groups, and the corresponding delete routes).
  • GET /api/admin/users/{id}/available-roles / .../available-role-groups — what can still be assigned.

SSO connections​

  • GET|POST /api/admin/sso-connections — configure per-tenant social/enterprise login (Google / Microsoft / GitHub). See the operator note in Product Concepts; provider registration is covered by the SSO provider setup runbook in the main repo.

Logs & monitoring​

  • Login attempts, event logs, and audit logs are exposed for viewing and filtering (the dashboard's logging views). Event logs also surface super_admin_access entries so tenant admins can see when DW-Corp support accessed their tenant.

Typical automation flow​

  1. Authenticate as an admin (obtain the session cookie).
  2. POST /api/admin/tenants to create a tenant + initial application.
  3. Capture the returned client_id and API key for the application.
  4. POST /api/admin/roles / POST /api/admin/role-groups to model permissions.
  5. Assign roles/groups to users as they sign up.

Where the full reference lives​

The complete request/response schemas, status codes, and examples are generated from the OpenAPI spec. Head to the API Reference — it explains the two surfaces (full internal vs. curated public) and how they will be rendered here.