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

# Authentication

> Authenticate to the MKA1 API with your API key, decide when to send X-On-Behalf-Of, and exchange an API key for a short-lived JWT.

Use your MKA1 API key in the `Authorization` header on every request.
For multi-user server-side integrations, also send `X-On-Behalf-Of` to identify the end user.

<Tip>
  Need the full request path, header propagation rules, and JWT exchange internals?
  Read the [authentication deep dive](/docs/authentication-deep-dive).
</Tip>

## Send your API key

Pass your API key as a bearer token.

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

Use `https://apigw.mka1.com` as the base URL.

<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({
    responsesCreateRequest: {
      model: 'auto',
      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: 'auto',
    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 = "auto",
      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="auto",
      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": "auto",
      "input": "Write a short welcome message."
    }'
  ```
</CodeGroup>

If your API key is missing, invalid, or does not have access to the requested resource, the MKA1 API returns an authentication or authorization error.

## Send `X-On-Behalf-Of` for an end user

Use `X-On-Behalf-Of` when your server is making a request for one of your end users.
Set the header value to your own stable end user identifier.

```http theme={null}
X-On-Behalf-Of: <end-user-id>
```

For example, if your app stores users as `user_123`, use that value consistently in requests made for that user.

<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({
    xOnBehalfOf: 'user_123',
    responsesCreateRequest: {
      model: 'auto',
      input: 'Summarize this support ticket.',
    },
  })
  ```

  ```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: 'auto',
    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 = "auto",
      Input = ResponsesCreateRequestInput.CreateStr("Summarize this support ticket."),
  });
  ```

  ```python Python SDK theme={null}
  res = sdk.llm.responses.create(
      model="auto",
      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": "auto",
      "input": "Summarize this support ticket."
    }'
  ```
</CodeGroup>

If your integration does not act for a specific end user, omit `X-On-Behalf-Of`.

## Choose the right pattern

Use only `Authorization` when:

* You are calling the MKA1 API for your own backend workflow.
* The request is not tied to a specific end user.

Use both `Authorization` and `X-On-Behalf-Of` when:

* Your server is acting for one of your end users.
* You want requests, responses, files, or usage to stay associated with that end user.

Do not send an email address or mutable display name unless that is already your stable end user identifier.
Use an ID from your own system that does not change.

## Exchange an API key for a JWT

Use `POST /api/v1/authentication/api-keys/exchange-token` when you need a short-lived JWT for a downstream service.
Send your MKA1 API key in `Authorization`.
Then pass a JSON body with:

* `audience`: The service URL that should accept the token.
* `externalUserId`: Your end user ID for the JWT subject.
* `expiresIn`: Optional token lifetime in seconds. The OpenAPI spec allows 300 to 2592000.
* `permissions`: Optional subset of API key permissions to embed in the token. If omitted, all API key permissions are used.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 auth api-keys exchange-token \
    --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.apiKeys.exchangeToken({
    requestBody: {
      audience: 'https://my-awesome-website.com',
      externalUserId: 'user_123',
      expiresIn: 3600,
      // permissions: ['agent:create', 'agent:read'],
    },
  })
  ```

  ```csharp C# SDK theme={null}
  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>() { "agent:create", "agent:read" },
      });

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

  ```python Python SDK theme={null}
  jwt = sdk.auth.api_keys.exchange_token(
      body={
          "audience": "https://my-awesome-website.com",
          "external_user_id": "user_123",
          "expires_in": 3600,
          # "permissions": ["agent:create", "agent:read"],
      }
  )

  # Use the JWT for subsequent requests
  authed = SDK(bearer_auth=f"Bearer {jwt.token}")
  ```

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

A successful response returns a JSON object with `token`.

## Use a JWT for subsequent requests

Once you have a JWT from the exchange endpoint, use it as a bearer token in place of your API key.
This lets you issue short-lived credentials to downstream services or end users without exposing your API key.

<CodeGroup>
  ```bash CLI theme={null}
  # Pass the JWT explicitly via -H to override MKA1_BEARER_AUTH
  mka1 llm responses create \
    --model auto \
    --input '"Write a short welcome message."' \
    -H 'Authorization: Bearer <jwt-token>'
  ```

  ```ts MKA1 SDK theme={null}
  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: 'auto',
      input: 'Write a short welcome message.',
    },
  })
  ```

  ```csharp C# SDK theme={null}
  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 = "auto",
      Input = ResponsesCreateRequestInput.CreateStr("Write a short welcome message."),
  });
  ```

  ```python Python SDK theme={null}
  # Use the JWT returned from the exchange endpoint
  authed = SDK(bearer_auth=f"Bearer {jwt.token}")

  res = authed.llm.responses.create(
      model="auto",
      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": "auto",
      "input": "Write a short welcome message."
    }'
  ```
</CodeGroup>

## Next steps

* Review the [API overview](/api-reference/introduction) for the base URL and the live OpenAPI spec.
* Read the [authentication deep dive](/docs/authentication-deep-dive) for the end-to-end gateway, JWT exchange, and downstream identity model.
* Learn how to control access to resources with [Authorization](/docs/authorization).