Autenticação e isolamento de tenants

No MKA1, o limite prático de tenant é:

uma chave de API de conta distinta
um ID de usuário final delegado opcional via X-On-Behalf-Of
propriedade e uso de recursos downstream registrados nesse contexto autenticado

Use o passo a passo abaixo quando quiser verificar que dois tenants estão isolados um do outro na prática. Ele fornece um fluxo exato de Tenant A / Tenant B que você pode executar de ponta a ponta.

Verifique o isolamento de tenants na prática

Trate cada tenant como uma conta separada com sua própria chave de API. O objetivo é mostrar quatro coisas:

Tenant A e Tenant B usam chaves de API diferentes.
Tenant A e Tenant B podem ter configurações de cota diferentes.
Tenant A e Tenant B podem ter políticas diferentes.
Um recurso criado no Tenant A não é acessível no Tenant B.

Etapa 1: defina dois tenants

Comece com duas chaves de API separadas.

export TENANT_A_KEY="<tenant-a-api-key>"
export TENANT_B_KEY="<tenant-b-api-key>"
export TENANT_A_USER="tenant_a_user"
export TENANT_B_USER="tenant_b_user"

Se você já tiver duas chaves de produção ou staging, poderá usá-las diretamente. Se precisar provisionar duas chaves com limites diferentes para a demonstração, crie-as separadamente.

curl https://apigw.mka1.com/api/v1/authentication/api-key/create/rate-limited \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Cookie: better-auth.session_token=<tenant-a-session>' \
  --data '{
    "name": "Chave de demonstração do Tenant A",
    "rateLimitEnabled": true,
    "rateLimitTimeWindow": 3600000,
    "rateLimitMax": 60
  }'

curl https://apigw.mka1.com/api/v1/authentication/api-key/create/rate-limited \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Cookie: better-auth.session_token=<tenant-b-session>' \
  --data '{
    "name": "Chave de demonstração do Tenant B",
    "rateLimitEnabled": true,
    "rateLimitTimeWindow": 3600000,
    "rateLimitMax": 600
  }'

Isso estabelece imediatamente as duas primeiras partes do isolamento:

Tenant A e Tenant B não compartilham uma chave.
Tenant A e Tenant B não compartilham a mesma configuração de cota.

Etapa 2: configure políticas diferentes para cada tenant

Agora atribua aos dois tenants políticas de proteção diferentes. Configure o Tenant A para bloquear a palavra confidential.

curl https://apigw.mka1.com/api/v1/llm/guardrails \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TENANT_A_KEY}" \
  --data '{
    "guardrails": [
      {
        "mode": "ban_words",
        "enabled": true,
        "config": {
          "words": ["confidential"]
        }
      }
    ]
  }'

Configure o Tenant B com uma política diferente.

curl https://apigw.mka1.com/api/v1/llm/guardrails \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TENANT_B_KEY}" \
  --data '{
    "guardrails": [
      {
        "mode": "ban_words",
        "enabled": true,
        "config": {
          "words": ["internal-only"]
        }
      }
    ]
  }'

Em seguida, teste o mesmo conteúdo em ambos os tenants. O Tenant A deve bloquear isto:

curl https://apigw.mka1.com/api/v1/llm/guardrails/test \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TENANT_A_KEY}" \
  --data '{
    "content": "Resuma este roteiro confidencial."
  }'

O Tenant B deve avaliar o mesmo conteúdo com base em sua própria política, em vez da política do Tenant A:

curl https://apigw.mka1.com/api/v1/llm/guardrails/test \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TENANT_B_KEY}" \
  --data '{
    "content": "Resuma este roteiro confidencial."
  }'

O resultado esperado é:

O Tenant A falha porque confidential está bloqueado na política do Tenant A.
O Tenant B não herda a política do Tenant A.

Esta é a demonstração prática mais clara de políticas independentes por tenant.

Etapa 3: demonstre cotas separadas

Após criar duas chaves com limites diferentes, envie o mesmo tipo de solicitação pelas duas chaves. O Tenant A usa a chave com limite baixo:

for i in $(seq 1 70); do
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --silent \
    --output /dev/null \
    --write-out "tenant-a request $i -> %{http_code}\n" \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer ${TENANT_A_KEY}" \
    --header "X-On-Behalf-Of: ${TENANT_A_USER}" \
    --data '{
      "model": "meetkai:functionary",
      "input": "Responda com a palavra ok."
    }'
done

O Tenant B usa a chave com limite mais alto:

for i in $(seq 1 70); do
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --silent \
    --output /dev/null \
    --write-out "tenant-b request $i -> %{http_code}\n" \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer ${TENANT_B_KEY}" \
    --header "X-On-Behalf-Of: ${TENANT_B_USER}" \
    --data '{
      "model": "meetkai:functionary-pt",
      "input": "Responda com a palavra ok."
    }'
done

O resultado esperado é:

O Tenant A começa a receber 429 antes.
O Tenant B continua tendo sucesso porque possui uma chave diferente e uma cota diferente.

Isso mostra que os tenants não compartilham um único limitador global.

Etapa 4: demonstre o isolamento de recursos

Crie um recurso no Tenant A. Uma conversa é um exemplo simples porque ela fica visível pela API pública.

curl https://apigw.mka1.com/api/v1/llm/conversations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TENANT_A_KEY}" \
  --header "X-On-Behalf-Of: ${TENANT_A_USER}" \
  --data '{
    "metadata": {
      "tenant": "A",
      "demo": "segregated-tenants"
    }
  }'

Suponha que a resposta retorne conv_tenant_a_123. O Tenant A pode lê-la:

curl https://apigw.mka1.com/api/v1/llm/conversations/conv_tenant_a_123 \
  --header "Authorization: Bearer ${TENANT_A_KEY}" \
  --header "X-On-Behalf-Of: ${TENANT_A_USER}"

O Tenant B não deve conseguir ler o mesmo recurso:

curl https://apigw.mka1.com/api/v1/llm/conversations/conv_tenant_a_123 \
  --header "Authorization: Bearer ${TENANT_B_KEY}" \
  --header "X-On-Behalf-Of: ${TENANT_B_USER}"

Você também pode mostrar o isolamento de listagem:

curl 'https://apigw.mka1.com/api/v1/llm/conversations?limit=20' \
  --header "Authorization: Bearer ${TENANT_B_KEY}" \
  --header "X-On-Behalf-Of: ${TENANT_B_USER}"

O Tenant B não deve ver a conversa do Tenant A em sua lista. Esta é a prova prática de enclave de tenant:

a mesma superfície de API é usada
a mesma plataforma é usada
mas identidade, política, cota e propriedade de recursos são aplicadas separadamente

Etapa opcional 5: mostre registros de uso separados

Se quiser mais um ponto de prova visível, consulte o uso separadamente para cada tenant.

curl 'https://apigw.mka1.com/api/v1/llm/usage/responses?start_time=1704067200&end_time=1704153600&bucket_width=1d&group_by=api_key_id' \
  --header "Authorization: Bearer ${TENANT_A_KEY}"

curl 'https://apigw.mka1.com/api/v1/llm/usage/responses?start_time=1704067200&end_time=1704153600&bucket_width=1d&group_by=api_key_id' \
  --header "Authorization: Bearer ${TENANT_B_KEY}"

O objetivo desta etapa não é apenas cobrança. Ela mostra que a plataforma registra a atividade no contexto autenticado do tenant, em vez de mesclar todo o tráfego em uma única conta indiferenciada.

O que este passo a passo comprova

Se você executar o passo a passo acima, poderá fazer estas afirmações exatas:

Chaves independentes: Tenant A e Tenant B se autenticam com chaves de API diferentes.
Cotas independentes: Tenant A e Tenant B podem ter configurações de limite de taxa diferentes e receber comportamentos 429 diferentes.
Políticas independentes: Tenant A e Tenant B podem definir proteções diferentes e obter resultados diferentes para o mesmo conteúdo.
Isolamento real: Um recurso criado no Tenant A não pode ser lido no Tenant B.

A superfície de API é compartilhada, mas o contexto autenticado do tenant, a aplicação de cotas, a configuração de políticas e a propriedade dos recursos não são compartilhados.

Como o modelo de identidade funciona internamente

A autenticação na API MKA1 tem três camadas:

Sua chave de API identifica sua conta.
X-On-Behalf-Of identifica o usuário final em nome de quem seu servidor está agindo.
Um JWT trocado fornece a um serviço downstream uma credencial de curta duração derivada dessa chave de API e do contexto de usuário final.

A versão curta é simples:

Envie Authorization: Bearer <mka1-api-key> em todas as solicitações do lado do servidor.
Adicione X-On-Behalf-Of quando a solicitação pertencer a um de seus usuários finais.
Use POST /api/v1/authentication/api-keys/exchange-token quando outro serviço precisar receber um token de curta duração em vez de sua chave de API bruta.

Se você precisar apenas do padrão de uso, comece pelo guia de autenticação. Esta página explica o que acontece depois que a solicitação chega ao gateway.

O caminho da solicitação

A API MKA1 não solicita que os serviços downstream validem tokens bearer por conta própria. As solicitações passam primeiro pelo gateway, e o gateway injeta cabeçalhos de identidade confiáveis para o restante da plataforma. Quando você também envia X-On-Behalf-Of, o gateway mantém essa identidade delegada de usuário final com a solicitação: A troca de JWT adiciona uma etapa extra:

Os três padrões principais

Padrão 1: solicitações somente de backend

Use este padrão quando seu backend estiver chamando a API MKA1 para seu próprio fluxo de trabalho e não houver um usuário final separado a ser rastreado.

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Escreva uma breve nota de lançamento para nossa atualização de API."
  }'

const response = await fetch("https://apigw.mka1.com/api/v1/llm/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.MKA1_API_KEY}`,
  },
  body: JSON.stringify({
    model: "meetkai:functionary-pt",
    input: "Escreva uma breve nota de lançamento para nossa atualização de API.",
  }),
});

Padrão 2: integração de servidor para múltiplos usuários

Use este padrão quando seu backend estiver fazendo a solicitação para um dos usuários da sua própria aplicação.

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user_123' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Resuma este ticket de suporte."
  }'

const response = await fetch("https://apigw.mka1.com/api/v1/llm/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.MKA1_API_KEY}`,
    "X-On-Behalf-Of": "user_123",
  },
  body: JSON.stringify({
    model: "meetkai:functionary-pt",
    input: "Resuma este ticket de suporte.",
  }),
});

Este é o padrão correto quando você deseja que solicitações, arquivos, respostas, conversas e uso permaneçam associados a um ID de usuário final estável do seu próprio sistema.

Padrão 3: troque sua chave de API por um JWT de curta duração

Use este padrão quando outro serviço precisar receber um token com duração limitada em vez de sua chave de API de longa duração.

curl https://apigw.mka1.com/api/v1/authentication/api-keys/exchange-token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "audience": "https://my-service.example.com",
    "externalUserId": "user_123",
    "expiresIn": 3600,
    "permissions": ["agent:create", "agent:read"]
  }'

const response = await fetch("https://apigw.mka1.com/api/v1/authentication/api-keys/exchange-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.MKA1_API_KEY}`,
  },
  body: JSON.stringify({
    audience: "https://my-service.example.com",
    externalUserId: "user_123",
    expiresIn: 3600,
    permissions: ["agent:create", "agent:read"],
  }),
});

const { token } = await response.json();

Quais cabeçalhos você envia versus quais cabeçalhos a plataforma injeta

Cabeçalhos que você envia

Cabeçalho	Obrigatório	Significado
`Authorization`	Sim	Sua chave de API MKA1 ou JWT trocado no formato bearer
`X-On-Behalf-Of`	Não	Seu identificador estável de usuário final para solicitações delegadas do lado do servidor

Cabeçalhos confiáveis injetados dentro da plataforma

Cabeçalho	Produzido por	Significado
`X-User-ID`	Gateway	O ID de usuário da conta autenticada
`X-Api-Key-ID`	Gateway	O ID da chave de API resolvida
`X-User-Role`	Gateway	O contexto de função autenticada
`X-Api-Key-Permissions`	Gateway	Permissões associadas à chave de API
`X-Exchange-JWT-External-User-ID`	Gateway	O ID de usuário final delegado
`X-Exchange-JWT-Permissions`	Gateway	Permissões incorporadas ao JWT trocado

Os clientes enviam Authorization e, às vezes, X-On-Behalf-Of. Os clientes não enviam diretamente os cabeçalhos internos X-User-ID ou X-Api-Key-ID. Eles são derivados pelo gateway após a validação.

Como a troca de JWT funciona

POST /api/v1/authentication/api-keys/exchange-token transforma uma chave de API de longa duração em um token de curta duração para outro serviço.

O caminho singular legado POST /api/v1/authentication/api-key/exchange-token (SDK: auth.apiKey.getJwtFromKey()) está obsoleto e será removido em uma versão futura. Use POST /api/v1/authentication/api-keys/exchange-token (SDK: auth.apiKeys.exchangeToken()) em seu lugar.

O corpo da solicitação tem quatro campos relevantes:

audience: a URL exata do serviço que deve aceitar o JWT
externalUserId: o ID de usuário final colocado no assunto do JWT
expiresIn: duração do token em segundos, de 300 a 2592000
permissions: um subconjunto opcional das permissões da chave de API

A resposta é:

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Uma carga útil de token decodificada tem esta aparência:

{
  "ak": "cm4xqw8ij0001w8lcmj9tn6v7",
  "sub": "user_123",
  "iat": 1734624000,
  "exp": 1734627600,
  "iss": "https://exchange.meetkai.com",
  "aud": "https://my-service.example.com",
  "permissions": ["agent:create", "agent:read"]
}

Estas declarações são as mais importantes:

ak: o ID da chave de API usado para pesquisa e aplicação de limite de taxa
sub: sua identidade delegada de usuário final
aud: o serviço que deve aceitar o token
permissions: o conjunto de capacidades permitidas para esse token

Como o escopo de tenant funciona na prática

A decisão de design mais importante é que a identidade do usuário final é explícita. Se você enviar X-On-Behalf-Of: user_123, os serviços downstream poderão manter recursos e uso associados a esse usuário. Isso importa para:

conversas salvas
respostas armazenadas
arquivos e armazenamentos de vetores
uso por usuário e trilhas de auditoria
verificações de autorização delegada

Quando você omite X-On-Behalf-Of, as solicitações são executadas como trabalho de conta somente de backend. Quando você o inclui, a solicitação se torna uma solicitação delegada para um usuário final específico. Use um identificador estável do seu próprio sistema. Não use um nome de exibição mutável, a menos que ele já seja seu ID de usuário canônico.

Limites de taxa e o que os chamadores devem esperar

As chaves de API podem ter configurações personalizadas de limite de taxa. O caminho de autenticação aplica limites de taxa por chave de API antes que a solicitação chegue aos serviços downstream. Na prática, isso significa:

duas chaves de API diferentes podem ter limites diferentes
uma chave de API sobrecarregada não implica que outra chave esteja esgotada
um 429 faz parte do caminho de autenticação, não é um erro de modelo downstream

O fluxo de troca de token também permanece vinculado à chave de API de origem. Isso significa que um JWT downstream ainda herda o comportamento de limite de taxa no nível da conta associado à chave de origem. Se quiser pools de tráfego separados para aplicações ou cargas de trabalho diferentes, use chaves de API separadas.

Erros comuns

Enviar `X-On-Behalf-Of` a partir de código de navegador

Não exponha sua chave de API em código de navegador ou cliente móvel. Seu servidor deve chamar a API MKA1 e anexar X-On-Behalf-Of nela.

Usar um identificador de usuário final instável

Use um ID interno durável, como user_123. Não alterne entre endereços de e-mail, nomes de usuário e nomes de exibição para o mesmo usuário.

Usar o `audience` incorreto em JWTs trocados

O serviço downstream deve validar o token para o público pretendido. Defina audience como a URL real do serviço que deve aceitar o JWT.

Solicitar permissões mais amplas que a chave de API

O endpoint de troca de token permite apenas um subconjunto das permissões da chave de API. Se você solicitar uma permissão que a chave de API não possui, a troca falhará.

Tratar cabeçalhos internos propagados como cabeçalhos públicos de cliente

Cabeçalhos como X-User-ID e X-Api-Key-ID fazem parte do caminho confiável de solicitação interna. Eles não substituem Authorization.

Apêndice do caminho de código

Os snippets a seguir mostram a principal forma de implementação por trás do comportamento público.

O Kong valida o token bearer e injeta cabeçalhos confiáveis

authorizationHeader = utils.StripBearer(authorizationHeader)

if utils.IsApiKey(authorizationHeader) {
    resp, err := c.authenticationClient.ValidateApiKey(ctx, authorizationHeader)
    if err != nil {
        c.handleAuthenticationServiceError(kong, err)
        return
    }

    c.writeApiKeyInfoToUnderlyingHeaders(kong, resp.GetApiKeyInfo())
    c.writeUserInfoToUnderlyingHeaders(kong, resp.GetUserInfo())

    onBehalfOfHeader, _ := kong.Request.GetHeader(headerOnBehalfOf)
    if onBehalfOfHeader != "" {
        c.writeExchangeJwtInfoToUnderlyingHeaders(kong, &authentication.ExchangeJWTInfo{
            ExternalUserId: onBehalfOfHeader,
            Permissions:    resp.GetApiKeyInfo().GetPermissions(),
        })
    }

    return
}

É por isso que os serviços downstream podem confiar em X-User-ID, X-Api-Key-ID e X-Exchange-JWT-External-User-ID após a validação do gateway.

O endpoint de troca de token verifica a chave de API, verifica permissões e assina o JWT

const apiKeyResult = await auth.api.verifyApiKey({
  body: {
    key: apiKey,
  },
});

if (!apiKeyResult.valid || !apiKeyResult.key) {
  ctx.set.status = 401;
  return { message: "Chave de API inválida" };
}

const apiKeyPermissions = Object.entries(verifiedKey.permissions ?? {}).map(
  ([key, value]) => `${key}:${value}`,
);
const permissions = validatedBody.permissions ?? apiKeyPermissions;

if (permissions.some((permission) => !apiKeyPermissions.includes(permission))) {
  ctx.set.status = 401;
  return { message: "Incompatibilidade de permissões" };
}

Em seguida, ele assina uma carga útil que inclui o ID da chave de API, o assunto do usuário final delegado e permissões filtradas:

payload: {
  ak: verifiedKey.id,
  sub: validatedBody.externalUserId,
  iat: DateTime.now().toUTC().toUnixInteger(),
  permissions: permissions,
}

Os serviços downstream leem a identidade de cabeçalhos confiáveis

const apiKey = reqHeaders.get(KONG_API_KEY_HEADER)?.trim();
const userId = reqHeaders.get(KONG_USER_ID_HEADER)?.trim();
const externalUserId = reqHeaders.get(KONG_EXTERNAL_USER_ID_HEADER)?.trim() ?? "";

if (!apiKey?.length || !userId?.length) {
  throw KONG_AUTH_ERROR;
}

return { apiKey, userId, externalUserId, userRole };

É por isso que os serviços por trás do gateway geralmente não analisam tokens bearer por conta própria. Em vez disso, eles operam com um contexto de identidade validado.

Próximas etapas

Use o guia de autenticação para a versão curta e exemplos de copiar e colar. Use a visão geral da API para inspecionar a referência gerada e a especificação OpenAPI ativa. Em seguida, consulte as páginas de endpoint relevantes na Referência da API para obter detalhes exatos de solicitação e resposta.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Autenticação e isolamento de tenants

Verifique o isolamento de tenants na prática

Etapa 1: defina dois tenants

Etapa 2: configure políticas diferentes para cada tenant

Etapa 3: demonstre cotas separadas

Etapa 4: demonstre o isolamento de recursos

Etapa opcional 5: mostre registros de uso separados

O que este passo a passo comprova

Como o modelo de identidade funciona internamente

O caminho da solicitação

Os três padrões principais

Padrão 1: solicitações somente de backend

Padrão 2: integração de servidor para múltiplos usuários

Padrão 3: troque sua chave de API por um JWT de curta duração

Quais cabeçalhos você envia versus quais cabeçalhos a plataforma injeta

Cabeçalhos que você envia

Cabeçalhos confiáveis injetados dentro da plataforma

Como a troca de JWT funciona

Como o escopo de tenant funciona na prática

Limites de taxa e o que os chamadores devem esperar

Erros comuns

Enviar `X-On-Behalf-Of` a partir de código de navegador

Usar um identificador de usuário final instável

Usar o `audience` incorreto em JWTs trocados

Solicitar permissões mais amplas que a chave de API

Tratar cabeçalhos internos propagados como cabeçalhos públicos de cliente

Apêndice do caminho de código

O Kong valida o token bearer e injeta cabeçalhos confiáveis

O endpoint de troca de token verifica a chave de API, verifica permissões e assina o JWT

Os serviços downstream leem a identidade de cabeçalhos confiáveis

Próximas etapas

​Verifique o isolamento de tenants na prática

​Etapa 1: defina dois tenants

​Etapa 2: configure políticas diferentes para cada tenant

​Etapa 3: demonstre cotas separadas

​Etapa 4: demonstre o isolamento de recursos

​Etapa opcional 5: mostre registros de uso separados

​O que este passo a passo comprova

​Como o modelo de identidade funciona internamente

​O caminho da solicitação

​Os três padrões principais

​Padrão 1: solicitações somente de backend

​Padrão 2: integração de servidor para múltiplos usuários

​Padrão 3: troque sua chave de API por um JWT de curta duração

​Quais cabeçalhos você envia versus quais cabeçalhos a plataforma injeta

​Cabeçalhos que você envia

​Cabeçalhos confiáveis injetados dentro da plataforma

​Como a troca de JWT funciona

​Como o escopo de tenant funciona na prática

​Limites de taxa e o que os chamadores devem esperar

​Erros comuns

​Enviar X-On-Behalf-Of a partir de código de navegador

​Usar um identificador de usuário final instável

​Usar o audience incorreto em JWTs trocados

​Solicitar permissões mais amplas que a chave de API

​Tratar cabeçalhos internos propagados como cabeçalhos públicos de cliente

​Apêndice do caminho de código

​O Kong valida o token bearer e injeta cabeçalhos confiáveis

​O endpoint de troca de token verifica a chave de API, verifica permissões e assina o JWT

​Os serviços downstream leem a identidade de cabeçalhos confiáveis

​Próximas etapas

Verifique o isolamento de tenants na prática

Etapa 1: defina dois tenants

Etapa 2: configure políticas diferentes para cada tenant

Etapa 3: demonstre cotas separadas

Etapa 4: demonstre o isolamento de recursos

Etapa opcional 5: mostre registros de uso separados

O que este passo a passo comprova

Como o modelo de identidade funciona internamente

O caminho da solicitação

Os três padrões principais

Padrão 1: solicitações somente de backend

Padrão 2: integração de servidor para múltiplos usuários

Padrão 3: troque sua chave de API por um JWT de curta duração

Quais cabeçalhos você envia versus quais cabeçalhos a plataforma injeta

Cabeçalhos que você envia

Cabeçalhos confiáveis injetados dentro da plataforma

Como a troca de JWT funciona

Como o escopo de tenant funciona na prática

Limites de taxa e o que os chamadores devem esperar

Erros comuns

Enviar `X-On-Behalf-Of` a partir de código de navegador

Usar um identificador de usuário final instável

Usar o `audience` incorreto em JWTs trocados

Solicitar permissões mais amplas que a chave de API

Tratar cabeçalhos internos propagados como cabeçalhos públicos de cliente

Apêndice do caminho de código

O Kong valida o token bearer e injeta cabeçalhos confiáveis

O endpoint de troca de token verifica a chave de API, verifica permissões e assina o JWT

Os serviços downstream leem a identidade de cabeçalhos confiáveis

Próximas etapas