Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Use sua chave de API MKA1 no cabeçalho Authorization em todas as requisições. Para integrações servidor-servidor com múltiplos usuários, envie também o X-On-Behalf-Of para identificar o usuário final.
Precisa do caminho completo da requisição, regras de propagação de cabeçalhos e detalhes internos da troca de JWT? Leia o guia aprofundado de autenticação.

​
Envie sua chave de API

Passe sua chave de API como um token bearer. 
Authorization: Bearer <mka1-api-key>
Use https://apigw.mka1.com como a URL base. 
export MKA1_BEARER_AUTH='Bearer <mka1-api-key>'

mka1 whoami -H 'X-On-Behalf-Of: <end-user-id>'
Se sua chave de API estiver ausente, inválida ou não tiver acesso ao recurso solicitado, a API MKA1 retornará um erro de autenticação ou autorização.

​
Envie X-On-Behalf-Of para um usuário final

Use X-On-Behalf-Of quando seu servidor estiver fazendo uma requisição em nome de um de seus usuários finais. Defina o valor do cabeçalho como o identificador estável do usuário final em seu sistema. 
X-On-Behalf-Of: <end-user-id>
Por exemplo, se seu aplicativo armazena usuários como user_123, use esse valor de forma consistente nas requisições feitas para esse usuário. 
mka1 whoami -H 'X-On-Behalf-Of: user_123'
Se sua integração não atua para um usuário final específico, omita o X-On-Behalf-Of.

​
Escolha o padrão correto

Use apenas Authorization quando:
  • Você está chamando a API MKA1 para um fluxo de trabalho interno do seu backend.
  • A requisição não está vinculada a um usuário final específico.
Use tanto Authorization quanto X-On-Behalf-Of quando:
  • Seu servidor está agindo em nome de um de seus usuários finais.
  • Você deseja que requisições, respostas, arquivos ou uso permaneçam associados a esse usuário final.
Não envie um endereço de e-mail ou nome de exibição mutável, a menos que já seja seu identificador estável de usuário final. Use um ID do seu próprio sistema que não mude.

​
Troque uma chave de API por um JWT

Use POST /api/v1/authentication/api-key/exchange-token quando precisar de um JWT de curta duração para um serviço downstream. Envie sua chave de API MKA1 em Authorization. Depois, envie um corpo JSON com:
  • audience: A URL do serviço que deve aceitar o token.
  • externalUserId: O ID do seu usuário final para ser o subject do JWT.
  • expiresIn: Tempo de vida opcional do token em segundos. O OpenAPI permite de 300 a 2592000.
mka1 auth api-key get-jwt-from-key \
  --audience https://my-awesome-website.com \
  --external-user-id user_123 \
  --expires-in 3600
Uma resposta bem-sucedida retorna um objeto JSON com token.

​
Use um JWT para requisições subsequentes

Assim que você tiver um JWT do endpoint de troca, use-o como token bearer no lugar da sua chave de API. Isso permite emitir credenciais de curta duração para serviços downstream ou usuários finais sem expor sua chave de API. 
# Passe o JWT explicitamente via -H para sobrescrever o MKA1_BEARER_AUTH
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Write a short welcome message."' \
  -H 'Authorization: Bearer <jwt-token>'

​
Próximos passos