Skip to main content
This page covers the most common questions and misunderstandings when integrating the Tenant Management API and using it together with the Documents API.

​
Conceptual model

​
What is the difference between Organization, Tenant, and Tenant Application?

  • Organization: Top-level container provisioned by Resistant AI. It owns tenants and organization-level applications.
  • Tenant: The primary isolation boundary. Data and configuration are separated per tenant.
  • Tenant Application: An OAuth2 machine-to-machine client inside a tenant, used only for authentication to the Documents API. A tenant can have multiple tenant applications.

​
Is it one-to-one mapping between my downstream customers and tenant applications?

No. The recommended mapping is one-to-one between downstream customers and tenants. Tenant applications are authentication clients that belong to a tenant. You may have:
  • one tenant application per region/cell, or
  • multiple tenant applications for key rotation or operational separation.

​
Do I pass tenant_id when calling the Documents API?

No. For the Documents API, the tenant is resolved implicitly from the tenant application credentials used to obtain the token. In other words:
  • You authenticate with a tenant application (client_id + secret or JWT)
  • Resistant AI infers the tenant from that credential
  • You do not add tenant_id as a parameter to Documents API calls

​
Is customer_tenant_id the same as tenant_id or tenant application ID?

No. customer_tenant_id is an optional, customer-defined identifier used in submission characteristics for downstream analytics/monitoring in scenarios where one tenant processes documents for multiple downstream customers. It is not:
  • the Resistant tenant identifier (tenant_id), nor
  • a tenant application identifier (client_id).
If you use one tenant per downstream customer, you can typically leave customer_tenant_id empty or set it to an internal non-PII identifier.

​
Authentication and scope separation

​
Can I use admin/org-level tokens to submit documents or fetch results?

No. Admin/org-level tokens are scoped to Tenant Management API operations (control plane) and cannot be used for Documents API operations (data plane). This separation is intentional.

​
Do RSA keys change with each deployment?

No. That’s a misunderstanding.
  • Client ID + Client Secret does not involve RSA keys.
  • If you use JWT client assertion (client_id + private key), the private key is your key:
    • store it securely (Secrets Manager / KMS),
    • reuse it across deployments,
    • rotate intentionally according to your security policy (not per deployment).

​
What if we lose the client secret?

Client secrets are typically shown only once at creation time (for security). If you lose it, the standard resolution is to rotate/recreate the tenant application secret (or create a new tenant application) and update your integration.

​
Region / cell behavior

​
Are tenants regional?

Tenants are “global” within your organization, but tenant applications are region/cell-specific. Your document processing occurs in the region/cell for the tenant application you use.

​
How do I choose regions/cells when creating a tenant?

Tenant creation supports specifying cells, with a default of ["eu-1"].
Available cells include: eu-1, us-1, ca-1, ap-2, ap-3. Choose cells based on:
  • where you need to process data (data residency / latency),
  • which regions your downstream customers require.

​
Is testing available in all regions?

Testing is provided in EU only. If you need testing in another region/cell, raise it with Resistant AI.

​
API usage and constraints

​
Why does “Create tenant” fail even though the name looks fine?

Tenant names are constrained. In production documentation, name must match:
  • ^[a-z0-9]{1,61}$ (lowercase letters and digits only, max length 61)
Common causes of failure:
  • uppercase letters,
  • hyphens/underscores/spaces,
  • length too long.

​
How do I page through tenant lists?

The list endpoint supports cursor-based pagination:
  • limit (default 20)
  • after_id cursor

​
Deletion and lifecycle

​
What are the tenant provisioning limits?

Default is 20 tenants per organization; can be increased on request.

​
Should we delete tenants?

Yes, treat tenants as a lifecycle-managed. Delete unused tenants (after deleteing their application), to avoid sprawl and keep access control clean.

​
Why can’t I delete a tenant?

To delete a tenant, you must first delete all tenant applications in that tenant (dependency cleanup). After applications are removed, you can delete the tenant.

​
What happens to documents/results if we delete a tenant?

Deletion behavior is intentionally strict. The exact effect depends on your retention and deletion policies. If you need formal guarantees for compliance, refer to your data retention/deletion policy and SLA.

​
Network/security questions

​
Do you support IP allowlisting?

No. IP allowlisting is not supported as an authentication mechanism. Use:
  • OAuth2 access tokens (tenant application credentials), and
  • domain-based egress allowlisting if your network policy requires it.

​
Troubleshooting checklist

If integration isn’t behaving as expected, check:
  • Are you using Tenant Management tokens only for Tenant Management endpoints?
  • Are you using tenant application tokens for Documents API calls?
  • Are you mixing testing vs production base URLs or token URLs?
  • Is the tenant name valid (^[a-z0-9]{1,61}$)?
  • Are you targeting the right cell(s) (eu-1, us-1, ca-1, ap-2, ap-3)?