> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retire a tenant

> Admin only. Retire a tenant, freeing the provider account it holds so any organization may connect it again. The tenant's tuned rate-limit configuration is kept, so re-adding the same provider account later restores it rather than starting from defaults.

Refused with 409 while anything still references the tenant — its credentials, its stored rate-limit budget, or queued dispatch work — because those records are keyed on it and would be left pointing at nothing. Nothing is written on a refusal, so the same request can be retried once the references are gone. No credential and no stored secret is ever removed by this operation. Idempotent: retiring an already-retired tenant succeeds. Cross-tenant access returns 404, never 403.



## OpenAPI

````yaml /openapi.json delete /tenants/{tenancy_id}
openapi: 3.1.0
info:
  title: GetDialed API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/v1
    description: Production
security: []
paths:
  /tenants/{tenancy_id}:
    delete:
      tags:
        - tenants
      summary: Retire a tenant
      description: >-
        Admin only. Retire a tenant, freeing the provider account it holds so
        any organization may connect it again. The tenant's tuned rate-limit
        configuration is kept, so re-adding the same provider account later
        restores it rather than starting from defaults.


        Refused with 409 while anything still references the tenant — its
        credentials, its stored rate-limit budget, or queued dispatch work —
        because those records are keyed on it and would be left pointing at
        nothing. Nothing is written on a refusal, so the same request can be
        retried once the references are gone. No credential and no stored secret
        is ever removed by this operation. Idempotent: retiring an
        already-retired tenant succeeds. Cross-tenant access returns 404, never
        403.
      operationId: delete_tenant_tenants__tenancy_id__delete
      parameters:
        - name: tenancy_id
          in: path
          required: true
          schema:
            type: string
            title: Tenancy Id
      responses:
        '204':
          description: Successful Response
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '403':
          description: Caller is authenticated but not an admin
          content:
            application/json:
              example:
                detail: Admin role required
        '404':
          description: >-
            No such tenant for this organization (cross-tenant access also
            returns 404)
          content:
            application/json:
              example:
                detail: Tenant not found
        '409':
          description: >-
            Blocking-reference protection: credentials, stored rate-limit budget
            records or queued dispatch work still reference this tenant, so
            removing it would strand them. The tenant is left intact — retry
            once nothing points at it.
          content:
            application/json:
              example:
                detail: >-
                  This tenant is still referenced by 2 credential(s) in this
                  account, so removing it would leave them pointing at nothing.
                  Detach them or let them finish first, then retry.
        '422':
          description: >-
            The request failed validation — an unknown sort field, a page size
            outside the permitted range, a filter pair that cannot both hold, an
            empty label, or a field other than `label` in a rename body.
          content:
            application/json:
              example:
                detail: is_manual=true and platform_id disagree
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              example:
                detail: 'Rate limit exceeded: 100 per 1 minute'
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````