---
title: "Create a key"
method: POST
path: "/tyk/keys"
tags: ["Keys"]
---

# Create a key

`POST /tyk/keys`

Tyk will generate the access token based on the OrgID specified in the API Definition and a random UUID. This ensures that keys can be "owned" by different API Owners should segmentation be needed at an organisational level.
<br/><br/>
API keys without access_rights data will be written to all APIs on the system (this also means that they will be created across all SessionHandlers and StorageHandlers, it is recommended to always embed access_rights data in a key to ensure that only targeted APIs and their back-ends are written to.

## Request body

- SessionState — There's a data structure that's based on this and it's used for Protocol Buffer support, make sure to update "coprocess/proto/coprocess_session_state.proto" and generate the bindings using: cd coprocess/proto && ./update_bindings.sh
  - `tags` string[]
  - `access_rights` object
  - `alias` string
  - `allowance` number, double
  - `apply_policies` string[]
  - `apply_policy_id` string
  - `basic_auth_data` object
    - `hash_type` string
    - `password` string
  - `certificate` string
  - `data_expires` integer
  - `enable_detail_recording` boolean
  - `expires` integer
  - `hmac_enabled` boolean
  - `hmac_string` string
  - `id_extractor_deadline` integer
  - `is_inactive` boolean
  - `jwt_data` object
    - `secret` string
  - `last_check` integer
  - `last_updated` string
  - `meta_data` object
  - `monitor` object
    - `trigger_limits` number[]
  - `oauth_client_id` string
  - `oauth_keys` object
  - `org_id` string
  - `per` number, double
  - `quota_max` integer
  - `quota_remaining` integer
  - `quota_renewal_rate` integer
  - `quota_renews` integer
  - `rate` number, double
  - `session_lifetime` integer
  - `smoothing` RateLimitSmoothing — Rate Limit Smoothing is a mechanism to dynamically adjust the request rate limits based on the current traffic patterns. It helps in managing request spikes by gradually increasing or decreasing the rate limit instead of making abrupt changes or blocking requests excessively. Once the rate limit smoothing triggers an allowance change, one of the following events is emitted: - `RateLimitSmoothingUp` when the allowance increases - `RateLimitSmoothingDown` when the allowance decreases Events are emitted based on the configuration: - `enabled` (boolean) to enable or disable rate limit smoothing - `threshold` after which to apply smoothing (minimum rate for window) - `trigger` configures at which fraction of a step a smoothing event is emitted - `step` is the value by which the rate allowance will get adjusted - `delay` is a hold-off in seconds providing a minimum period between rate allowance adjustments To determine if the request rate is growing and needs to be smoothed, the `step * trigger` value is subtracted from the request allowance and, if the request rate goes above that, then a RateLimitSmoothingUp event is emitted and the rate allowance is increased by `step`. Once the request allowance has been increased above the `threshold`, Tyk will start to check for decreasing request rate. When the request rate drops `step * (1 + trigger)` below the request allowance, a `RateLimitSmoothingDown` event is emitted and the rate allowance is decreased by `step`. After the request allowance has been adjusted (up or down), the request rate will be checked again over the next `delay` seconds and, if required, further adjustment made to the rate allowance after the hold-off. For any allowance, events are emitted based on the following calculations: - When the request rate rises above `allowance - (step * trigger)`, a RateLimitSmoothingUp event is emitted and allowance increases by `step`. - When the request rate falls below `allowance - (step + step * trigger)`, a RateLimitSmoothingDown event is emitted and allowance decreases by `step`. Example: Threshold: 400, Request allowance: 600, Current rate: 500, Step: 100, Trigger: 0.5. To trigger a RateLimitSmoothingUp event, the request rate must exceed: - Calculation: Allowance - (Step * Trigger). - Example: 600 - (100 * 0.5) = `550`. Exceeding a request rate of `550` will increase the allowance to 700 (Allowance + Step). To trigger a RateLimitSmoothingDown event, the request rate must fall below: - Calculation: Allowance - (Step + (Step * Trigger)). - Example: 600 - (100 + (100 * 0.5)) = 450. As the request rate falls below 450, that will decrease the allowance to 500 (Allowance - Step). The request allowance will be smoothed between `threshold`, and the defined `rate` limit (maximum). The request allowance will be updated internally every `delay` seconds.
    - `delay` integer — Delay is a hold-off between smoothing events and controls how frequently the current allowance will step up or down (in seconds).
    - `enabled` boolean — Enabled indicates if rate limit smoothing is active.
    - `step` integer — Step is the increment by which the current allowance will be increased or decreased each time a smoothing event is emitted.
    - `threshold` integer — Threshold is the initial rate limit beyond which smoothing will be applied. It is a count of requests during the `per` interval and should be less than the maximum configured `rate`.
    - `trigger` number, double — Trigger is a fraction (typically in the range 0.1-1.0) of the step at which point a smoothing event will be emitted as the request rate approaches the current allowance.
  - `throttle_interval` number, double
  - `throttle_retry_limit` integer

## Response `200`

New Key added

- ApiModifyKeySuccess — apiModifyKeySuccess represents when a Key modification was successful
  - `action` string
  - `key` string — in:body
  - `key_hash` string
  - `status` string

## Other responses

- `400` — Malformed data

## Changes

- **2024-06-17** `1938d97cb6b5` — 2 info
  - added the new optional request property `access_rights/additionalProperties/limit/smoothing`
  - added the new optional request property `smoothing`
- **2022-05-24** `111d8ca21864` — 20 breaking, 17 warning, 5 info
  - the request property `access_rights` became not nullable
  - the request property `access_rights/additionalProperties/allowed_urls` became not nullable
  - the request property `access_rights/additionalProperties/allowed_urls/items/methods` became not nullable
  - the request property `access_rights/additionalProperties/versions` became not nullable
  - …38 more

[Change history](https://skmtc.dev/tyktechnologies/apis/tyk-gateway-api/changes/tyk/keys/post.md)

---

[API](https://skmtc.dev/tyktechnologies/apis/tyk-gateway-api.md) · [All operations](https://skmtc.dev/tyktechnologies/apis/tyk-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tyktechnologies/apis/tyk-gateway-api/revisions/73c372f49eab?raw)