> ## 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.

# Autenticação

> Autentique-se na API MKA1 com sua chave de API, decida quando enviar X-On-Behalf-Of e troque uma chave de API por um JWT de curta duraçã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.

<Tip>
  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](/pt/docs/authentication-deep-dive).
</Tip>

## Envie sua chave de API

Passe sua chave de API como um token bearer.

```http theme={null}
Authorization: Bearer <mka1-api-key>
```

Use `https://apigw.mka1.com` como a URL base.

<CodeGroup>
  ```bash CLI theme={null}
  export MKA1_BEARER_AUTH='Bearer <mka1-api-key>'

  mka1 whoami -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```ts MKA1 SDK theme={null}
  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.',
  })
  ```

  ```ts OpenAI SDK theme={null}
  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.',
  })
  ```

  ```csharp C# SDK theme={null}
  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."),
  });
  ```

  ```python Python SDK theme={null}
  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.",
  )
  ```

  ```bash bash theme={null}
  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."
    }'
  ```
</CodeGroup>

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.

```http theme={null}
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.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 whoami -H 'X-On-Behalf-Of: user_123'
  ```

  ```ts MKA1 SDK theme={null}
  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' },
    }
  )
  ```

  ```ts OpenAI SDK theme={null}
  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.',
  })
  ```

  ```csharp C# SDK theme={null}
  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."),
  });
  ```

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

  ```bash bash theme={null}
  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."
    }'
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 auth api-key get-jwt-from-key \
    --audience https://my-awesome-website.com \
    --external-user-id user_123 \
    --expires-in 3600
  ```

  ```ts MKA1 SDK theme={null}
  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,
  })
  ```

  ```csharp C# SDK theme={null}
  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);
  ```

  ```python Python SDK theme={null}
  jwt = sdk.auth.api_key.get_jwt_from_key()

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

  ```bash bash theme={null}
  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
    }'
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash CLI theme={null}
  # 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>'
  ```

  ```ts MKA1 SDK theme={null}
  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.',
  })
  ```

  ```csharp C# SDK theme={null}
  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."),
  });
  ```

  ```python Python SDK theme={null}
  # 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.",
  )
  ```

  ```bash bash theme={null}
  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."
    }'
  ```
</CodeGroup>

## Próximos passos

* Revise a [visão geral da API](/pt/api-reference/introduction) para a URL base e o OpenAPI spec ao vivo.
* Leia o [guia aprofundado de autenticação](/pt/docs/authentication-deep-dive) 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](/pt/docs/authorization).