Autenticação

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>'

import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

const response = await mka1.llm.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Write a short welcome message.',
})

import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
})

const response = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Write a short welcome message.',
})

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "meetkai:functionary-pt",
    Input = ResponsesCreateRequestInput.CreateStr("Write a short welcome message."),
});

from mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Write a short welcome message.",
)

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": "Write a short welcome message."
  }'

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'

import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

const response = await mka1.llm.responses.create(
  {
    model: 'meetkai:functionary-pt',
    input: 'Summarize this support ticket.',
  },
  {
    headers: { 'X-On-Behalf-Of': 'user_123' },
  }
)

import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': 'user_123' },
})

const response = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Summarize this support ticket.',
})

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "meetkai:functionary-pt",
    Input = ResponsesCreateRequestInput.CreateStr("Summarize this support ticket."),
});

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Summarize this support ticket.",
    http_headers={"X-On-Behalf-Of": "user_123"},
)

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": "Summarize this support ticket."
  }'

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

import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

const result = await mka1.auth.apiKey.exchangeToken({
  audience: 'https://my-awesome-website.com',
  externalUserId: 'user_123',
  expiresIn: 3600,
})

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var result = await sdk.Auth.ApiKey.GetJwtFromKeyAsync(
    xOnBehalfOf: "<end-user-id>",
    body: new GetJwtFromKeyRequestBody()
    {
        Audience = "https://my-awesome-website.com",
        ExternalUserId = "user_123",
        ExpiresIn = 3600,
    });

Console.WriteLine(result.Object!.Token);

jwt = sdk.auth.api_key.get_jwt_from_key()

# Use o JWT para requisições subsequentes
authed = SDK(bearer_auth=f"Bearer {jwt.token}")

curl https://apigw.mka1.com/api/v1/authentication/api-key/exchange-token \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "audience": "https://my-awesome-website.com",
    "externalUserId": "user_123",
    "expiresIn": 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>'

import { SDK } from '@meetkai/mka1'

// Use o JWT retornado do endpoint de troca
const mka1 = new SDK({ bearerAuth: `Bearer ${result.token}` })

const response = await mka1.llm.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Write a short welcome message.',
})

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

// Use o JWT retornado do endpoint de troca
var jwtSdk = new SDK(bearerAuth: $"Bearer {result.Object!.Token}",
    serverUrl: "https://apigw.mka1.com");

var res = await jwtSdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
{
    Model = "meetkai:functionary-pt",
    Input = ResponsesCreateRequestInput.CreateStr("Write a short welcome message."),
});

# Use o JWT retornado do endpoint de troca
authed = SDK(bearer_auth=f"Bearer {jwt.token}")

res = authed.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Write a short welcome message.",
)

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer <jwt-token>" \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Write a short welcome message."
  }'

Próximos passos

Revise a visão geral da API para a URL base e o OpenAPI spec ao vivo.
Leia o guia aprofundado de autenticação para entender o gateway de ponta a ponta, troca de JWT e modelo de identidade downstream.
Aprenda como controlar o acesso a recursos com Autorização.

​Envie sua chave de API

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

​Escolha o padrão correto

​Troque uma chave de API por um JWT

​Use um JWT para requisições subsequentes

​Próximos passos

Envie sua chave de API

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

Escolha o padrão correto

Troque uma chave de API por um JWT

Use um JWT para requisições subsequentes

Próximos passos