Skip to main content

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 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.
Need the full request path, header propagation rules, and JWT exchange internals? Read the authentication deep dive.

​
Send your API key

Pass your API key as a bearer token. 
Authorization: Bearer <mka1-api-key>
Use https://apigw.mka1.com as the base URL. 
export MKA1_BEARER_AUTH='Bearer <mka1-api-key>'

mka1 whoami -H 'X-On-Behalf-Of: <end-user-id>'
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. 
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. 
mka1 whoami -H 'X-On-Behalf-Of: user_123'
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-key/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.
mka1 auth api-key get-jwt-from-key \
  --audience https://my-awesome-website.com \
  --external-user-id user_123 \
  --expires-in 3600
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. 
# 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>'

​
Next steps