> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Managing API keys Use Runtype API keys to authenticate programmatic requests to the Runtype API. Create keys on the **API** page in **Settings**. Assign permissions and set expiration dates. ## Understand Runtype API keys A Runtype API key lets a script, CI pipeline, or application trigger Flows, manage resources, and read data through the Runtype API. Runtype uses other key types for other services: * **Product API keys** authenticate requests to API Surfaces. * **Provider API keys** authenticate requests to external AI model providers. This page uses "API key" to mean a Runtype API key. ## Before you begin * Sign in to the [Runtype Dashboard](https://use.runtype.com). * Select an organization. Each API key belongs to an organization. > **Note** > > You can create, edit, regenerate, reveal, and delete API keys only from the dashboard. A request that authenticates with an API key cannot manage API keys and returns a 403 error. ## Choose an environment When you create a key, you select an environment. You cannot change the environment later. To move an integration from Test to Production, create a Production key and update the integration. * **Production** keys start with `rt_live_`. The dashboard shows a Production key only once, when you create or regenerate it. * **Test** keys start with `rt_test_`. You can reveal an active Test key at any time. Test keys have these limits: * 20 executions per day for the organization. A Test key stops running executions after your organization reaches 20 executions in a day. Executions that don't use the Test key also count toward this limit. The count resets at midnight UTC. * 200 executions over the key's lifetime. * Test keys support only a subset of permissions. A Test key ignores other permissions that you select. For example, a Test key cannot delete resources, manage API keys, or use integrations or schedules. Use a Production key for these operations. Test API keys for API Surfaces are a different key type with a different limit. For details, see [Setting up an API surface](/user-guide/products-surfaces/setting-up-an-api-surface). ## Choose permissions Permissions control the API operations that a key can perform. Select a permission template to apply a common set of permissions, or select individual permissions in **Permissions**. Grant only the permissions that your integration requires. | Template | Use it to | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Full Access | Access all resources and operations | | Read Only | Read core resources without changing them | | Flows & Prompts | Create and run Flows, with Record access | | Data Management | Fully manage Records and data | | Analytics Only | View analytics and usage data | | Products & Surfaces | Manage Products, Surfaces, and capabilities | | Agents Management | Create and manage Agents | | Messaging | Manage messaging channels and conversations | | Messaging (Read Only) | View messaging channels and conversation history | | SDK Integration | Use the common permissions for SDK and API integrations | | A2A Client | Run A2A tasks and read task status | | Telemetry Ingest | Send traces from agents that run outside Runtype. See [Reporting telemetry from an external agent](/developer-guides/guides/reporting-external-telemetry). | ## Create an API key To create an API key, follow these steps: 1. On **Settings > API**, click **Create New API Key**. 2. In the **Name** field, enter a descriptive name. 3. In **Environment**, select **Test** or **Production**. For the differences, see [Choose an environment](#choose-an-environment). 4. Optional: In **Permission Template**, select a template. 5. In **Permissions**, select the permissions that the integration requires. 6. Optional: In **Expiration Date**, select a date. Leave the field empty for no expiration. 7. Click **Create API Key**. 8. Copy the key or download the key file, and store the key securely. The dashboard does not show a Production key again. ## Use an API key Send an API key in the `Authorization` header as a Bearer token. The following cURL command lists your Flows. The key must have the **Flows (Read)** or **Flows (Full)** permission. **`List Flows`** ```bash title="List Flows" curl https://api.runtype.com/v1/flows \ -H "Authorization: Bearer rt_live_YOUR_API_KEY" ``` Replace `rt_live_YOUR_API_KEY` with your API key. Store the key in an environment variable or a secrets manager. Do not put it in source code. ## Edit or deactivate an API key You can change the name, permissions, and expiration date of a key that you created. You cannot change its environment or organization. To edit an API key, follow these steps: 1. On **Settings > API**, find the key. If the list has more than 10 keys, use the search box to search by name, prefix, or permission. 2. Click the settings icon (gear) for the key. 3. In the **Edit API Key** dialog, change **Name**, **Permissions**, or **Expiration Date**. 4. Click **Update API Key**. To stop a key from working without deleting it, turn off the switch in the key's row. The key's status changes to **Inactive**, and requests that use it fail authentication. Turn the switch on again to restore the key. ## Regenerate an API key Regenerate an API key to replace its secret. The key keeps its name, permissions, expiration date, and environment. To regenerate an API key, follow these steps: 1. On **Settings > API**, find the key that you want to replace. 2. Click the regenerate icon (circular arrow) for the key. 3. In the confirmation dialog, click **Regenerate API Key**. The previous key value stops working. 4. Copy the replacement key from the success dialog. 5. Update your applications and integrations to use the replacement key. ## Delete an API key Delete an API key to revoke it permanently. After deletion, requests that use the key fail authentication. To disable a key temporarily, deactivate it instead. To delete an API key, follow these steps: 1. On **Settings > API**, find the key that you want to revoke. 2. Click the delete icon (trash can) for the key. 3. In the confirmation dialog, click **Delete API Key**. ## Read key status Each key row shows badges for the key's status: * **Active** or **Inactive**: whether the key's switch is on. An inactive key fails authentication. * **Expired**: the expiration date has passed. The key stays in the list but fails authentication. To restore access, set a later date in **Expiration Date**, or create a key. * **Test**: the key is a Test key. After you reveal the key, the row also shows the number of lifetime executions remaining. When none remain, the row shows **Limits reached**. ## Troubleshoot authentication errors | Status | Cause | Resolution | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | 401 | The key is invalid, inactive, expired, deleted, or was regenerated. | Check the key's status on **Settings > API**. Activate the key, update its expiration date, or use the current key value. | | 403 with `Insufficient permissions` | The key does not have the permission that the endpoint requires. Some responses name the required permission. | Add the permission in **Edit API Key**. | | 403 on a Test key | The operation is not available to Test keys. Some responses include the code `TEST_KEY_PERMISSION_DENIED`. | Use a Production key. | | 429 with `TEST_KEY_DAILY_LIMIT_EXCEEDED` | Your organization reached 20 executions today. | Wait until the time in `resetTime`, or use a Production key. | | 429 with `TEST_KEY_LIFETIME_LIMIT_EXCEEDED` | The Test key used its 200 lifetime executions. | Create a Production key. | For more about authentication, see [Authentication](/developer-guides/getting-started/authentication). ## View organization API keys as an admin If you have the **Admin** role in an organization, **Settings > API** lists every API key that any member of the organization created. Members see only the keys that they created. If the list has more than 10 keys, admins can also search it by owner. A key that another member created shows the owner's name and a **View only** badge in place of the action buttons. You cannot edit, regenerate, reveal, or delete a key that another member created. The partial key characters after the prefix are also hidden for keys that you did not create. This wider view applies only to the dashboard. A request that authenticates with an API key always lists the keys of the user who created that key, even if that user is an admin. For role details, see [Team members and permissions](/user-guide/settings/team-members-and-permissions). ## Understand key ownership An API key belongs to the user who created it and to the organization that was active when the user created it. You cannot change either one. To move access to another organization, create a key in that organization and delete the old key. ## Protect API keys Follow these practices to protect your API keys: * **Use separate keys.** Create a key for each integration, CI pipeline, or script. * **Store keys securely.** Use environment variables or a secrets manager instead of source code. * **Grant least privilege.** Select only the permissions that each integration requires. * **Set expiration dates.** Set an expiration date when you create or edit a key. * **Regenerate exposed keys.** Replace a key if you expose it in a public repository, log, or client-side application. * **Review usage.** Open the **Analytics** tab on the **API** page to review key activity. Admins see activity for every key in the organization, with an **Owner** column. From a terminal, run `runtype api-keys list` and `runtype api-keys analytics`. ## Next steps Use these guides to continue: * [API reference overview](/api-reference/overview): find endpoint and request details * [Authentication](/developer-guides/getting-started/authentication): learn how the Runtype API authenticates requests * [Managing secrets](/user-guide/settings/managing-secrets): store credentials that your tools and Flows reference * [Setting up an API surface](/user-guide/products-surfaces/setting-up-an-api-surface): expose Flows and Agents through REST endpoints * [Authenticating with product API keys](/user-guide/products-surfaces/authenticating-with-product-api-keys): authenticate requests to API Surfaces