> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/preparation/authentication.md).

# API Authentication

This page explains how to authenticate with the MaiAgent API and obtain API keys

MaiAgent uses API keys for authentication.

## Authentication Method

All API requests must include an API key in the HTTP Header in the following format:

```javascript
const headers = {
  "Authorization": "Api-Key YOUR_API_KEY_HERE",
  "Content-Type": "application/json"
}
```

The header prefix is `Api-Key`, not `Bearer`. For rules on which member a key is bound to, how permissions are determined, and when a key becomes invalid, see [Common API Conventions: Authentication](/api/en/preparation/conventions.md#authentication).

## How to Obtain an API Key

There are two ways to obtain an API key. Both types of keys are used in the same way:

* **Self-issued by a member**: Any active organization member can create a key for themselves in the admin console by selecting the avatar in the upper-right corner → <mark style="color:blue;">Account</mark> → <mark style="color:blue;">API Keys</mark>. No additional permissions are required.
* **Issued by an administrator**: Administrators with the "API Key Management" permission can issue keys for specific members under <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">API Key Management</mark>, and configure an expiration time and requests per minute (RPM).

For instructions, see [API Key Management](https://docs.maiagent.ai/org/developer/api-keys) in the user manual: [Creating Your Own Key](https://docs.maiagent.ai/org/developer/api-keys#self-issued-keys) and [Creating an API Key as an Administrator](https://docs.maiagent.ai/org/developer/api-keys#create-api-key).

{% hint style="success" %}

* **Security reminder**: Keep your API key secure and do not share it publicly
* **Key format**: An API key consists of two alphanumeric parts, a prefix and a secret, separated by `.`. Include the entire key when making requests
  {% endhint %}

{% hint style="warning" %}
The full key is displayed only once, when it is successfully created. The list subsequently shows only some characters, and the full key cannot be viewed or recovered. If you did not save it, create a new key, update the services that use it, and then revoke the old key.
{% endhint %}

## Cannot Find an Old System-Issued Key <a href="#system-issued-api-key" id="system-issued-api-key"></a>

The <mark style="color:blue;">API Keys</mark> page in your personal account lists only keys you created yourself. When you first join an organization (including your first login through AD), the system may automatically issue a key with no expiration date, but it does not provide the full value, so you cannot obtain that key to make API calls. To call the API, create a new key on your personal page and save the full value immediately after creation.

For keys issued automatically by the system or on behalf of a member by an administrator, only members with organization key management permissions can view their owner, prefix, issuance source, status, and expiration date under <mark style="color:blue;">Organization Key Management</mark>. This page does not display the full value. If you do not have this permission, ask the organization owner or a member with organization key management permissions to help identify or revoke the old key.

## API Key Permissions <a href="#api-key-permissions" id="api-key-permissions"></a>

When you call the API with an API key, your permissions match the key owner's role permissions in that organization. The API returns 403 Forbidden if the required permissions are missing.

Write operations on members (`members`) and roles (`groups`) require the <mark style="color:blue;">Organization Overview</mark> subpermission (under <mark style="color:blue;">Organization Permissions</mark>). Organization owners are exempt from this requirement. This applies to the following operations:

* Add a member: `POST /api/v1/organizations/{organizationPk}/members/`
* Remove a member: `DELETE /api/v1/organizations/{organizationPk}/members/{id}/`
* Change a member's roles: `POST /api/v1/organizations/{organizationPk}/members/{id}/update-groups/`
* Create, update, or delete roles: `POST` / `PUT` / `PATCH` / `DELETE /api/v1/organizations/{organizationPk}/groups/…`
* Add or remove role members in bulk, or assign or remove a role's AI assistants, inboxes, knowledge bases, and databases: `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-*/…`
* Other write operations on members and roles (such as importing members in bulk) are also subject to this requirement

{% hint style="info" %}
Permissions are evaluated at the subpermission level. If the parent <mark style="color:blue;">Organization Permissions</mark> checkbox is unchecked in the role settings, this does not mean the child <mark style="color:blue;">Organization Overview</mark> checkbox is unchecked. To troubleshoot a 403 response, go to <mark style="color:blue;">Organization Settings → Roles</mark> in the admin console, expand <mark style="color:blue;">Organization Permissions</mark>, and check whether <mark style="color:blue;">Organization Overview</mark> is selected for the key owner's role.
{% endhint %}

## Error Handling

When authentication fails, the API returns the HTTP error code 401 Unauthorized:

* **Missing, malformed, or invalid API key**

A missing key, an incorrectly formatted header, or an invalid key (nonexistent, expired, disabled, revoked, or bound to a member who has been disabled or removed from the organization) all produce the same response, without specifying the reason:

```json
{
  "detail": "Authentication credentials were not provided."
}
```

*Troubleshooting: Check that the request header is `Authorization: Api-Key YOUR_API_KEY` and that the API key is complete, with no extra spaces or characters. If authentication still fails with the correct format, check in <mark style="color:blue;">API Key Management</mark> that the key is not disabled, expired, or revoked, and that its associated member is still active.*

* **Using an API key after `Bearer`**

The platform validates it as a login token and returns a different response:

```json
{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [ … ]
}
```

*Troubleshooting: Change the prefix to `Api-Key`.*

`401` responses include a `WWW-Authenticate` header, whose value is `Bearer realm="api"` for most endpoints. Use the status code to identify the error; do not use this header to decide which type of credential to send. See [Common API Conventions: Authentication Error Responses](/api/en/preparation/conventions.md#auth-errors). A valid key with insufficient permissions results in `403`; see [API Key Permissions](#api-key-permissions) above.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/en/preparation/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.