---
title: "Create a temporary API key"
method: POST
path: "/api/temporary-keys/"
tags: ["Temporary API Keys"]
---

# Create a temporary API key

`POST /api/temporary-keys/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/temporary-keys/`
- Auth: HTTP bearer

## Request body

- object
  - `name` string: Key name.
  - `expiry_date` string, date-time: Expiry date (ISO 8601).
  - `max_usage` integer: Max usage count. -1 = unlimited.
  - `rate_limit` integer: Calls per minute. Overridden by plan limit.
  - `spending_limit` number: Spending limit in USD for gateway usage.
  - `is_test` boolean: Test key (`true`) or production key (`false`).
  - `limit_policies` APIKeyLimitPolicySpec[]: Caps to create and scope to this key. The response includes each created policy with its `id`, `meter_definition_id`, and `current_state`. Once a block rule's cap is reached, gateway requests with the key get `429`.
    - `max_value` number, required: The cap, in the unit named by `metric`. The counter blocks when it reaches this value: `max_value` of 3 on `request_count` allows two requests and refuses the third.
    - `metric` 'cost' | 'request_count' | 'token_count': What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls.
    - `period` string, required: A named bucket (`minute`, `hour`, `day`, `week`, `month`) or a positive integer of seconds as a string. A lifetime (`null`) period is rejected here; use `POST /api/limit-policies/` for that.
    - `warning_threshold` number, nullable: Optional soft threshold; must be strictly below `max_value`. Fires an alert without blocking.
    - `name` string: Display label. When blank, the dashboard falls back to the key's own name.
    - `notification_method_id` string, nullable: OrganizationNotificationMethod id to ping when a rule trips. Must belong to the same project.

## Response `201`

Created API key.

- object
  - `id` string: API key ID.
  - `name` string: Key name.
  - `prefix` string: Key prefix.
  - `is_test` boolean: Test or production key.
  - `expiry_date` string, date-time: Expiry date.
  - `max_usage` integer: Max usage count. -1 = unlimited.
  - `rate_limit` number, nullable: Requests per minute. null uses the organization default.
  - `spending_limit` number, nullable: Spending limit in USD. `null` when not set.
  - `api_key` string: The API key value. Only returned on creation - store it securely.
  - `key_usage` integer: Number of times this key has been used.
  - `created` string, date-time: When the API key was created.
  - `unique_organization_id` string, nullable: Owning organization UUID.

## Other responses

- `400`: Validation failed, for example an invalid limit policy.
- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 7 breaking, 7 info
  - request body became required
  - the `limit_policies/items/warning_threshold` request property type changed from `number, null` to `number`, and format from `double` to no format
  - the response property `rate_limit` became nullable for the status `201`
  - the response property `spending_limit` became nullable for the status `201`
  - …10 more
- **2026-10-02** `b830b79cfd52`: 1 breaking, 3 info
  - the response property `spending_limit` became nullable for the status `201`
  - added the non-success response with the status `400`
  - added the non-success response with the status `403`
  - removed the non-success response with the status `401`
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-api-key` removed and replaced with `temporaryApiKeys_createApiKey`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/temporary-keys/post.md)

---

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