> 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/maiagent-user-guide/en/org/developer/api-keys.md).

# API Key Management

Manage API Keys for all members in your organization: issue keys on behalf of members in three steps, restrict available models and RPM/TPM, disable and revoke keys, view last-used time; and how membe

An API Key lets an external system, script, MCP client, or AI Gateway call MaiAgent as a specific member. Each key is bound to one member and one organization, and calls made with it have exactly the same permissions as that member.

There are two places to manage keys:

* **Administrators**: In <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">API Key Management</mark>, view all keys in the organization, issue keys on behalf of members, restrict available models and rate limits, and disable or revoke keys.
* **Members themselves**: On the account page under <mark style="color:blue;">API Keys</mark>, create and revoke their own keys. See [Members Creating Their Own Keys](#self-issued-keys).

## Who Can Use It <a href="#permissions" id="permissions"></a>

| Action                                                                                                                                           | Requirement                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enter <mark style="color:blue;">API Key Management</mark>; view, issue, disable, and revoke all keys in the organization                         | The <mark style="color:blue;">API Key Management permission</mark> under the <mark style="color:blue;">Organization Permissions</mark> role permission (organization owners have it by default; for how to configure it, see [Edit Role Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#edit-role-permissions)) |
| Create and revoke your own keys on the account page                                                                                              | Any active member of the organization; no extra permission is needed                                                                                                                                                                                                                                                                                      |
| Set <mark style="color:blue;">Provisioned Models</mark>, view this month's spending, and use <mark style="color:blue;">Access Diagnostics</mark> | The organization has enabled [AI Gateway](https://docs.maiagent.ai/maiagent-user-guide/en/build/ai-gateway.md)                                                                                                                                                                                                                                            |

## Key Concepts <a href="#key-concepts" id="key-concepts"></a>

* **The full key is shown only once**: The full key is displayed when it is created. Once you close the dialog, you can no longer see it, and the list shows only the <mark style="color:blue;">Prefix</mark>. If you lose it, revoke the old key and create a new one.
* **No limit on the number of keys**: Each member can hold multiple active keys at the same time. When rotating keys, you can create the new key first, update your integration settings, and then revoke the old key, so service is not interrupted.
* **How to call**: The platform API takes `Authorization: Api-Key <key>` in the HTTP header; the OpenAI-compatible endpoint of AI Gateway takes `Authorization: Bearer <key>`. For complete examples, see the technical manual's [API Quickstart](https://docs.maiagent.ai/tech/api-integration/quickstart) and [AI Gateway: OpenAI-Compatible API Integration](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible).

### Key Sources <a href="#key-sources" id="key-sources"></a>

The <mark style="color:blue;">Source</mark> column of the list shows who issued the key, and you can filter by it using <mark style="color:blue;">Filter by Source</mark>:

| Source                                         | Description                                                                                                                               |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">System-issued</mark> | Created automatically by the system when a member joins the organization; the name is a string of member ID characters                    |
| <mark style="color:blue;">Self-created</mark>  | Created by the member on the account page                                                                                                 |
| <mark style="color:blue;">Admin-issued</mark>  | Created for a member by an administrator in <mark style="color:blue;">API Key Management</mark>; the issuer's name is shown below the tag |

### Key Statuses <a href="#key-statuses" id="key-statuses"></a>

| Status                                    | Description                                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Active</mark>   | Can be used for calls normally                                                                           |
| <mark style="color:blue;">Disabled</mark> | Paused by an administrator; the key and its usage history are kept, and it can be re-enabled at any time |
| <mark style="color:blue;">Expired</mark>  | Past the configured expiration time                                                                      |
| <mark style="color:blue;">Revoked</mark>  | Permanently invalid and cannot be restored                                                               |

Disabled, expired, and revoked keys, as well as keys of members who have been removed, are rejected as invalid keys when used in calls.

## How to Access <a href="#how-to-enter" id="how-to-enter"></a>

From the left menu, click <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">API Key Management</mark>. The list is sorted by creation time, newest first, with the columns <mark style="color:blue;">Owner</mark>, <mark style="color:blue;">Name</mark>, <mark style="color:blue;">Prefix</mark>, <mark style="color:blue;">Source</mark>, <mark style="color:blue;">Status</mark>, <mark style="color:blue;">Provisioned Models・Rate</mark>, <mark style="color:blue;">Last Used</mark>, <mark style="color:blue;">Expiration Time</mark>, and <mark style="color:blue;">Created At</mark>.

* The search box at the top searches by name, owner, or Email, and you can also filter by source and status.
* <mark style="color:blue;">Last Used</mark> is the most recent time the key passed authentication; it is updated at most once per minute for the same key. Keys that have never been used show `-`.

## Create an API Key <a href="#create-api-key" id="create-api-key"></a>

Click <mark style="color:blue;">Create API Key</mark> in the upper-right corner to open the three-step <mark style="color:blue;">New API Key</mark> dialog.

{% stepper %}
{% step %}

### Select a Member <a href="#step-select-member" id="step-select-member"></a>

In <mark style="color:blue;">Select Member</mark>, search for and select the member the key will be bound to. The <mark style="color:blue;">API Key Name</mark> is filled in automatically as "Member Name's API Key" and can be edited (up to 50 characters). After you select a member, the screen shows the number of models that member can reach.

If you do not need any restrictions, you can click <mark style="color:blue;">Skip Settings and Generate Key</mark> directly: the key is created with default values (all reachable models enabled, no rate limit, never expires, enabled immediately). To set restrictions, click <mark style="color:blue;">Next: Provisioning and Limits</mark>.
{% endstep %}

{% step %}

### Provisioning and Limits <a href="#step-provision-and-limits" id="step-provision-and-limits"></a>

All of the following settings are optional, and they can also be adjusted in the key settings after creation:

| Field                                                              | Purpose                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Provisioned Models</mark>                | The models this key can use when chatting through AI Gateway; all are selected by default. You can only narrow the selection within the "reachable" scope (models available to the organization and opened by the Gateway); it cannot exceed what the organization has available. It does not affect the Embedding endpoint |
| <mark style="color:blue;">Requests Per Minute (RPM)</mark>         | The number of platform API calls this key can make per minute. This counts not only AI Gateway but also regular platform API calls. Leave blank for no limit                                                                                                                                                                |
| <mark style="color:blue;">Tokens Per Minute (TPM)</mark>           | The number of Tokens this key can use per minute for inference through AI Gateway. It is calculated over fixed one-minute intervals, so a single request may push that minute's usage slightly over the limit, after which further requests in the same minute are rejected. Leave blank for no limit                       |
| <mark style="color:blue;">Expiration Time</mark>                   | The time the key becomes invalid; leave blank for never expires                                                                                                                                                                                                                                                             |
| <mark style="color:blue;">Enable immediately after creation</mark> | If unchecked, the key is "Disabled" after creation, and you can enable it when needed                                                                                                                                                                                                                                       |

If the organization has not enabled AI Gateway, <mark style="color:blue;">Provisioned Models</mark> does not appear, and the other fields can still be set as usual. After you finish, click <mark style="color:blue;">Generate Key</mark>.
{% endstep %}

{% step %}

### Generate the Key <a href="#step-generate-key" id="step-generate-key"></a>

The screen shows the full key. Click the copy button to save it right away, then click <mark style="color:blue;">Confirm and Close</mark>. After closing, you can no longer view the full key.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If you close the dialog before "Generate Key", the key may already have been created but the full key can no longer be displayed. Find the key in the list, revoke it, and create it again.
{% endhint %}

## Manage Existing Keys <a href="#manage-keys" id="manage-keys"></a>

Each key has four actions on its right side:

| Action                                                                             | Description                                                                                                                                                                       |
| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Manage</mark>                                            | Opens the <mark style="color:blue;">Key Settings and Usage</mark> side panel (see below)                                                                                          |
| <mark style="color:blue;">Access Diagnostics</mark>                                | Checks why this key cannot call a model, listing each check that failed (see [AI Gateway Overview](https://docs.maiagent.ai/maiagent-user-guide/en/build/ai-gateway.md#overview)) |
| <mark style="color:blue;">Disable</mark> / <mark style="color:blue;">Enable</mark> | Pauses or resumes this key; takes effect immediately after confirmation                                                                                                           |
| <mark style="color:blue;">Revoke</mark>                                            | Permanently stops this key and cannot be undone                                                                                                                                   |

The <mark style="color:blue;">Key Settings and Usage</mark> side panel has two sections:

* <mark style="color:blue;">Key Settings</mark>: the <mark style="color:blue;">Enabled</mark> switch, RPM, TPM, <mark style="color:blue;">Expiration Time</mark> (blank = never expires), and <mark style="color:blue;">Provisioned Models</mark>. After making changes, click <mark style="color:blue;">Save</mark>; they take effect immediately.
* <mark style="color:blue;">Usage This Month</mark>: <mark style="color:blue;">Spending This Month (credits)</mark>, the bound member's <mark style="color:blue;">Member Quota</mark>, and the <mark style="color:blue;">Models Called・Spending</mark> breakdown. Spending and the model breakdown are shown only when the organization has enabled AI Gateway.

**Choosing between disabling and revoking**: If you only want to temporarily stop an integration from making calls (for example, to investigate abnormal traffic), use disable; you can re-enable it later. If you are sure the key will no longer be used or it has been leaked, use revoke.

{% hint style="warning" %}
Features such as Voice Agent and meeting records call the platform in the background as a member, provided that the member still has at least one active key. After you revoke or disable all of a member's keys (including the one issued automatically by the system), these features may no longer work as that member. When rotating keys, create the new key first, and then revoke the old one.
{% endhint %}

## Members Creating Their Own Keys <a href="#self-issued-keys" id="self-issued-keys"></a>

Members do not need administrative permissions to create a personal key for themselves:

1. Click your avatar in the upper-right corner → <mark style="color:blue;">Account</mark>.
2. On the left, under the current organization name, click <mark style="color:blue;">API Keys</mark>.
3. Click <mark style="color:blue;">Create Key</mark> (when you have no keys yet, the button is <mark style="color:blue;">Create Your First Key</mark>), enter a <mark style="color:blue;">Name</mark>, and optionally fill in an <mark style="color:blue;">Expiration Time</mark>.
4. After copying the full key shown on the screen, click <mark style="color:blue;">Confirm and Close</mark>.

A personal key is created in the **organization you are currently switched to**, and it calls the API with your own identity and permissions. If you belong to multiple organizations, switch to the one you want to use before creating it.

This page lists only the keys you created yourself, and you can revoke keys whose status is Active. Keys issued to you by an administrator or automatically by the system are managed by the organization administrator in <mark style="color:blue;">API Key Management</mark>. Members with the <mark style="color:blue;">API Key Management permission</mark> see an <mark style="color:blue;">Organization Key Management</mark> link at the top of this page, which takes them directly to the organization's key list.

Personal keys cannot set provisioned models or RPM/TPM on their own; if you need restrictions, ask an administrator to adjust them in <mark style="color:blue;">API Key Management</mark>.

## FAQ <a href="#faq" id="faq"></a>

#### Q: Can each member have only one active key? <a href="#faq-key-count" id="faq-key-count"></a>

No. Each member can hold multiple active keys at the same time, with no limit on the number.

#### Q: The API Key Management page opens blank? <a href="#faq-blank-page" id="faq-blank-page"></a>

Check in order:

1. Your role has the <mark style="color:blue;">API Key Management permission</mark> (see [Who Can Use It](#permissions)); if you only want to create a key for yourself, use [Members Creating Their Own Keys](#self-issued-keys) instead.
2. Switch to the correct organization in the upper-left corner and refresh the page; if your browser has cached an old version of the page, force a refresh (Windows `Ctrl+F5`, macOS `Cmd+Shift+R`).
3. If your company network or a browser extension blocks requests to the API domain, the list fails to load; try a different network or an incognito window.

If the page is still blank, send the error messages from your browser developer tools Console and your organization name to your MaiAgent contact.

#### Q: I forgot to copy the full key. What should I do? <a href="#faq-lost-key" id="faq-lost-key"></a>

The full key is shown only once, at creation, and the system cannot retrieve it again. Revoke this key and create a new one.

#### Q: Why can't I see the key an administrator created for me on my personal page? <a href="#faq-missing-in-profile" id="faq-missing-in-profile"></a>

The personal page shows only the keys you created yourself. For admin-issued and system-issued keys, ask an administrator with the <mark style="color:blue;">API Key Management permission</mark> to view or revoke them.

#### Q: The <mark style="color:blue;">Access Diagnostics</mark> button cannot be clicked? <a href="#faq-diagnose-disabled" id="faq-diagnose-disabled"></a>

Access diagnostics requires the organization to have AI Gateway enabled. When it is not enabled, the button shows "This organization has not enabled AI Gateway, so diagnostics are unavailable."; revoked keys also cannot be diagnosed.

## Further Reading <a href="#further-reading" id="further-reading"></a>

* [AI Gateway](https://docs.maiagent.ai/maiagent-user-guide/en/build/ai-gateway.md): Use an API Key to call the organization's models and fallback groups
* [MaiAgent MCP](https://docs.maiagent.ai/tech/mcp/maiagent-mcp): Use an API Key to let AI tools such as Claude operate the platform
* [OAuth Applications](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/oauth-applications.md): Let MCP clients use OAuth authorization instead of pasting an API Key
* [Member Credits Quota Management](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md): Limit the Credits that the member bound to a key can use


---

# 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/maiagent-user-guide/en/org/developer/api-keys.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.
