Autenticação

Use sua chave de API MKA1 no cabeçalho Authorization em todas as solicitações. Para integrações do lado do servidor com vários usuários, envie também X-On-Behalf-Of para identificar o usuário final.

Precisa do caminho completo da solicitação, das regras de propagação de cabeçalhos e dos detalhes internos da troca de JWT? Leia a análise detalhada da 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 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({
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    input: 'Escreva uma breve mensagem de boas-vindas.',
  },
})

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: 'Escreva uma breve mensagem de boas-vindas.',
})

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("Escreva uma breve mensagem de boas-vindas."),
});

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Escreva uma breve mensagem de boas-vindas.",
)

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 mensagem de boas-vindas."
  }'

Se sua chave de API estiver ausente, for 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 solicitação para um de seus usuários finais. Defina o valor do cabeçalho como seu próprio identificador estável de usuário final.

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 solicitaçõ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({
  xOnBehalfOf: 'user_123',
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    input: 'Resuma este ticket de suporte.',
  },
})

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: 'Resuma este ticket de suporte.',
})

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("Resuma este ticket de suporte."),
});

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Resuma este ticket de suporte.",
    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": "Resuma este ticket de suporte."
  }'

Se sua integração não atuar para um usuário final específico, omita X-On-Behalf-Of.

Escolha o padrão correto

Use apenas Authorization quando:

Você estiver chamando a API MKA1 para seu próprio fluxo de trabalho de backend.
A solicitação não estiver vinculada a um usuário final específico.

Use tanto Authorization quanto X-On-Behalf-Of quando:

Seu servidor estiver atuando para um de seus usuários finais.
Você quiser que solicitaçõ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 esse 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-keys/exchange-token quando precisar de um JWT de curta duração para um serviço downstream. Envie sua chave de API MKA1 em Authorization. Em seguida, passe um corpo JSON com:

audience: A URL do serviço que deve aceitar o token.
externalUserId: Seu ID de usuário final para o sujeito do JWT.
expiresIn: Duração opcional do token em segundos. A especificação OpenAPI permite de 300 a 2592000.
permissions: Subconjunto opcional dos escopos da chave (suas permissões, por exemplo read:responses ou read:files) a incorporar no token. Se omitido, o token carrega todos os escopos que a chave tem. Um token pode restringir os escopos da chave, mas nunca ampliá-los.

mka1 auth api-keys exchange-token \
  --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.apiKeys.exchangeToken({
  requestBody: {
    audience: 'https://my-awesome-website.com',
    externalUserId: 'user_123',
    expiresIn: 3600,
    // permissions: ['read:responses', 'read:files'],
  },
})

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

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

var result = await sdk.Auth.ApiKeys.ExchangeTokenAsync(
    body: new ExchangeApiKeyTokenRequestBody()
    {
        Audience = "https://my-awesome-website.com",
        ExternalUserId = "user_123",
        ExpiresIn = 3600,
        // Permissions = new List<string>() { "read:responses", "read:files" },
    });

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

jwt = sdk.auth.api_keys.exchange_token(
    audience="https://my-awesome-website.com",
    external_user_id="user_123",
    expires_in=3600,
    # permissions=["read:responses", "read:files"],
)

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

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-awesome-website.com",
    "externalUserId": "user_123",
    "expiresIn": 3600
  }'

Uma resposta bem-sucedida retorna um objeto JSON com token.

Use um JWT para solicitações subsequentes

Depois de obter um JWT do endpoint de troca, use-o como um token bearer no lugar de 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 substituir MKA1_BEARER_AUTH
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Escreva uma breve mensagem de boas-vindas."' \
  -H 'Authorization: Bearer <jwt-token>'

import { SDK } from '@meetkai/mka1'

// Use the JWT returned from the exchange endpoint
const mka1 = new SDK({ bearerAuth: `Bearer ${result.token}` })

const response = await mka1.llm.responses.create({
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    input: 'Escreva uma breve mensagem de boas-vindas.',
  },
})

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

// Use the JWT returned from the exchange endpoint
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("Escreva uma breve mensagem de boas-vindas."),
});

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

res = authed.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Escreva uma breve mensagem de boas-vindas.",
)

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": "Escreva uma breve mensagem de boas-vindas."
  }'

Próximas etapas

Consulte a visão geral da API para obter a URL base e a especificação OpenAPI em tempo real.
Leia a análise detalhada da autenticação para conhecer o gateway de ponta a ponta, a troca de JWT e o modelo de identidade downstream.
Saiba como controlar o acesso a recursos com Autorização.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Autenticaçã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 solicitações subsequentes

Próximas etapas

​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 solicitações subsequentes

​Próximas etapas

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 solicitações subsequentes

Próximas etapas