---
title: "Change a function's runtime key"
method: PUT
path: "/functions/{id}/runtime-key"
tags: ["Functions"]
---

# Change a function's runtime key

`PUT /functions/{id}/runtime-key`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/functions/{id}/runtime-key`
- Auth: HTTP bearer

Change the key the function runs with, or the secrets attached to it. A grant wider than the caller's own is refused. A custom runtime_grant must list addresses or send mail_scope "org" for every mailbox; one that does neither is refused (400 validation_error, details.reason mail_scope_required). The function is redeployed with the new key.

## Path parameters

- `id` string, uuid, required

## Request body

- SetFunctionRuntimeKeyRequest
  - `runtime_grant` union
    - string
    - object
      - `preset` string, required
      - `addresses` string[]
      - `permissions` string[]
      - `mail_scope` 'org'
  - `attached_secret_keys` string[]

## Response `200`

Change a function's runtime key

- object
  - `success` true, required
  - `data` SetFunctionRuntimeKeyResult, required
    - `mode` 'org_shared' | 'per_function', required
    - `preset` string, nullable, required
    - `permissions` string[], nullable, required
    - `mail_scope` unknown, required
    - `attached_secret_keys` string[], nullable, required
    - `key_prefix` string, nullable, required
    - `expires_at` string, nullable, required
    - `suspended_at` string, nullable, required
    - `suspended_reason` string, nullable, required
    - `function_bound_key` 'live' | 'revoked', nullable
    - `suspended_by` 'transfer' | 'access_decision' | 'owner_or_admin' | 'other', nullable
    - `stop_rank` 'owner' | 'admin', nullable
    - `key_suspension_reasons` string[]
    - `transfer_stop_placed` boolean

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: Resource not found
- `409`: conflict, runtime_grant_unavailable, function_suspended (details.reason suspended, access_stop or owner_or_admin_stop), suspension_undecided, rotation_in_progress or rotation_unconfirmed: the key could not be changed now; the message says why and whether a retry finishes it
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)