Trocar o admintoken

POST /admin/token/rotate

Gera um novo admintoken e invalida o atual na hora. Chame com o token atual no header admintoken e guarde o novo, que vem em admin_token.

• Uma troca a cada 24 horas; antes disso, 429 diz quando a próxima é permitida.
• Antes de responder, a api confirma o token novo com a Orkesio. Se não conseguir, desfaz a troca e responde 502: o token atual continua valendo.
• Os tokens das inboxes não mudam.
• Em servidor de demonstração, a troca é bloqueada (403).

Erro no formato v1. Esta rota é a mesma do v1 (mesmo handler), então o erro sai no formato antigo, {"error": "texto"}, sem o código estável do OrkesioError. É a exceção ao padrão da Orkesio; trate pelo status HTTP.

Autenticação

[
  {
    "admintoken": []
  }
]

{
  "admintoken": {
    "name": "admintoken",
    "type": "apiKey",
    "in": "header",
    "description": "Token de administrador para endpoints administrativos"
  }
}

Respostas

{
  "200": {
    "description": "Admin token rotacionado com sucesso",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "success",
            "message",
            "admin_token",
            "license_sync_triggered",
            "license_synced",
            "timestamp"
          ],
          "properties": {
            "success": {
              "type": "boolean",
              "example": true,
              "description": "Sempre `true`."
            },
            "message": {
              "type": "string",
              "example": "Admin token rotated successfully"
            },
            "admin_token": {
              "type": "string",
              "minLength": 50,
              "maxLength": 50,
              "pattern": "^[A-Za-z0-9]{50}
quot;,
              "description": "O novo `admintoken`. Use-o no header `admintoken` daqui em diante.",
              "example": "AbC123Def456GhI789JkL012MnO345PqR678StU901VwX234Yz"
            },
            "license_sync_triggered": {
              "type": "boolean",
              "example": true,
              "description": "Sempre `true`: a api enviou o token novo para a Orkesio."
            },
            "license_synced": {
              "type": "boolean",
              "example": true,
              "description": "Sempre `true` no sucesso: a Orkesio confirmou o token novo (sem confirmação, a resposta é `502`)."
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "description": "Timestamp Unix em milissegundos.",
              "example": 1776892800000
            }
          }
        }
      }
    }
  },
  "401": {
    "description": "admintoken inválido ou ausente",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "Unauthorized"
            }
          }
        }
      }
    }
  },
  "403": {
    "description": "Troca bloqueada em servidor de demonstração.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "Admin token rotation is disabled for free containers"
            }
          }
        }
      }
    }
  },
  "429": {
    "description": "Rotação bloqueada por cooldown de 24 horas",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "error",
            "last_rotated_at",
            "next_rotation_at",
            "retry_after_ms"
          ],
          "properties": {
            "error": {
              "type": "string",
              "example": "Admin token rotation cooldown active"
            },
            "last_rotated_at": {
              "type": "integer",
              "format": "int64",
              "description": "Timestamp Unix em milissegundos da última rotação concluída.",
              "example": 1776892800000
            },
            "next_rotation_at": {
              "type": "integer",
              "format": "int64",
              "description": "Timestamp Unix em milissegundos de quando uma nova rotação será permitida.",
              "example": 1776979200000
            },
            "retry_after_ms": {
              "type": "integer",
              "format": "int64",
              "description": "Tempo restante em milissegundos para liberar nova rotação.",
              "example": 86400000
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Erro interno ao rotacionar o token",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "example": "Failed to persist admin token"
            }
          }
        }
      }
    }
  },
  "502": {
    "description": "A api não conseguiu confirmar o token novo com a Orkesio e desfez a troca: o token atual continua valendo. Tente de novo.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "success",
            "error",
            "license_synced",
            "timestamp"
          ],
          "properties": {
            "success": {
              "type": "boolean",
              "example": false
            },
            "error": {
              "type": "string",
              "example": "Failed to sync rotated admin token with license server"
            },
            "license_synced": {
              "type": "boolean",
              "example": false
            },
            "timestamp": {
              "type": "integer",
              "format": "int64",
              "example": 1776892800000,
              "description": "Unix em milissegundos."
            }
          }
        }
      }
    }
  }
}

Estado: Disponível

Formato: o mesmo da API v1 (caminho, campos e erros no padrão antigo).

Compatibilidade de canais

Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em GET /events): o resultado vem só na resposta.

Antes e depois (uazapi → Orkesio)

Na uazapi: POST /admin/token/rotate.

• Sem mudança: a mesma rota e o mesmo formato da uazapi.

Guias relacionados

Visão geral · O que funciona em cada canal · O que muda da uazapi