# API Key for Android Automation: Create, Scope and Rotate

> Create an API key for Android automation in MAS, send it as X-API-KEY or swap it for an MCP token, and handle expiry, scopes, rate limits and revocation.

Source: https://automationmacro.com/docs/api-keys (Integrate, updated 2026-09-04)

An API key lets your own scripts and AI clients drive your Android automation as you, without the desktop app. Macro Automation Studio (MAS) uses one kind of key for two doors: the [REST API](/docs/rest-api), which takes the key in an `X-API-KEY` header, and the [MCP server](/docs/mcp), which exchanges the key for a one-hour bearer token. This page covers creating, using, limiting and retiring keys.

## Before you start

- MAS is installed and you are signed in. Keys are created in the app; there is no other way to mint one.
- Your account has an active subscription or trial. API traffic is refused without one.

## Create a MAS API key

1. In MAS, open **API Keys**.
2. Under **Create a key**, enter a **Name**. It is a label for the list and not part of the secret.
3. Choose **Expires**: **In 30 days**, **In 90 days**, **In 1 year** or **Never**. The default is 90 days.
4. Under **Permissions (scopes)**, tick the capabilities the key may use, or leave every box empty for full access. The scopes are explained below.
5. Click **Create key**.
6. In the **Your new API key** dialog, click **Copy** and store the key somewhere safe, then click **Done**.

The key is `mas_` followed by 48 hexadecimal characters. The server stores only a hash, so the dialog is the only moment you can read the full key. If you close it without copying, revoke the key and create another.

The **Integrations (MCP)** page creates the same kind of key from its **Create an MCP credential** panel. Keys made there never expire and start with `devices:control`, `macros:run` and `maps:read` ticked, which suits a client that drives devices and runs macros.

> [!NOTE]
> The dialog shows a sample `curl` command. Use the host `api.automationmacro.com` for every request, as on the [REST API](/docs/rest-api) page.

## Use the API key in your Android automation

Send the key in an `X-API-KEY` header. Every route that accepts a key resolves it to you, so the response matches what the app would get.

```bash
curl -H "X-API-KEY: mas_your_key" "https://api.automationmacro.com/api/executions?page_size=10"
```

For MCP, the key is the `client_secret` in a client-credentials exchange at `https://api.automationmacro.com/api/mcp/oauth/token`; the token lives one hour and carries the key's scopes. The command is on the [MCP server page](/docs/mcp). The key itself never reaches the MCP endpoint.

## The key list

**Your keys** lists every key, revoked ones included, with its **Name**, the first twelve characters of the **Key**, its **State** (**Active**, **Revoked** or **Expired**), **Last used** and **Expires**. Last used updates on each request that passes the checks below.

## API rate limit and key limits

MAS applies three checks to key traffic. None of them touch the app's own session.

| Check | Limit | Response when exceeded |
|---|---|---|
| Active keys | 25 active keys per account. Revoked and expired keys do not count. | `422` with "You already have 25 active API keys (max 25). Revoke one to create another." |
| Rate limit per key | 120 requests per minute | `429` with `rate_limit_exceeded` and a `Retry-After` header |
| Rate limit per user | 300 requests per minute across all your keys | `429` with `X-RateLimit-Scope: account` |
| Subscription | An active plan or trial | `402` with `subscription_required` |

The rate limit is a fixed one-minute window counted per key and then per account. A `429` carries `Retry-After` in seconds plus `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (a Unix timestamp) and `X-RateLimit-Scope` (`key` or `account`). Back off until the reset; more keys do not buy more throughput, because the account ceiling covers all of them.

A `402` means the key is valid but its owner has no active subscription or trial. Keys are not deleted when a plan lapses; they start working again when you resubscribe. Plans are on the [pricing page](/pricing) and the mechanics on the [billing page](/docs/billing).

Errors use one envelope:

```json
{"message": "Access Denied", "details": {"code": "invalid_api_key"}}
```

The codes you can see on key traffic are `missing_api_key`, `invalid_api_key` (unknown, revoked or expired), `api_key_not_user_scoped`, `missing_credentials`, `rate_limit_exceeded` and `subscription_required`.

## API key scopes

A key can carry five scopes. You choose them when you create the key, and they cannot be changed afterwards; create a new key for a different set. No scopes ticked means full access.

| Scope | Label in the app | What it allows on the MCP server |
|---|---|---|
| `devices:control` | Control devices | Lease a cloud device, take screenshots, tap, type, read text, find images, open and close apps |
| `macros:run` | Run macros | List and read your macros; start, check and stop runs |
| `macros:author` | Author macros | Start, follow, answer and stop a MAS Agent authoring session, which spends AI credits |
| `maps:read` | Read maps | Read the learned menu map of an app |
| `runs:read` | Read runs | Reserved: no tool requires it today |

Scopes are enforced by the MCP server only; a tool call without the right scope returns an error result naming it. The REST API ignores scopes, so any active key can call every route that accepts a key. For an AI client, tick the smallest set it needs.

## Rotate an API key

Keys cannot be edited or extended, so rotation means replacing.

1. Create a new key with the same scopes and a fresh expiry.
2. Move your scripts or MCP client to the new key. For MCP, mint a new token from it.
3. Click the revoke icon in the old key's row. The button is labelled **Revoke key** and takes effect at once.

Create the new key before revoking the old one so the switch has no gap. An expired key answers `401` with `invalid_api_key` and shows as **Expired** in the list.

## Revoke a key

Revoke a key the moment you suspect it has leaked. The next request with it gets `401`; an MCP token already minted from it works only until its own hour runs out. Revoked keys stay in the list, showing when they were last used, and free a slot toward the 25 active keys.

## Keys are personal

A key always acts as the person who created it: it reads and writes that person's devices, groups, profiles, proxies and webhooks, and its access rides that person's own subscription. Organization scoping is not available through keys.

## Key management needs the app

The routes that list, create and revoke keys (`/api/api-keys`) accept only the app's signed-in session, never a key. A leaked key therefore cannot mint a replacement for itself or extend its own life, so revoking it really ends the compromise. Manage keys on the **API Keys** page.

## Troubleshooting

### 401 invalid_api_key

The key is unknown, revoked or past its expiry, or the header was mistyped. The header name is `X-API-KEY` and the value is the full key including `mas_`. Check the key's **State** in the list and create a new one if it is not **Active**.

### 402 subscription_required

The key is fine, but the account has no active subscription or trial. Open **Subscription** in the app. See [Billing](/docs/billing).

### 429 rate_limit_exceeded

You sent more than 120 requests in a minute with one key, or more than 300 across all keys. Wait for the number of seconds in `Retry-After`, then continue at a lower rate.

### You already have 25 active API keys

The account is at its limit. Revoke a key you no longer use; expired keys already do not count.