> ## Documentation Index > Fetch the complete documentation index at: https://docs.rootly.com/llms.txt > Use this file to discover all available pages before exploring further. # Rotate an API key > Rotate an API key's token. Issues a new secret token and returns it — **the new token is only shown once**, so store it securely. **Self-only:** You can only rotate the API key that was used to authenticate this request. Attempting to rotate a different key returns `403 Forbidden`. **Grace period:** When enabled for your organization, the previous token remains valid after rotation, giving you time to deploy the new token without downtime. Pass `grace_period_minutes` (integer, 0–1440, default 30) to control how long the old token stays valid. Set to 0 to immediately invalidate the old token. The `grace_period_ends_at` field in the response confirms the exact time the old token will stop working. **Expiration:** Optionally provide a new `expires_at` date (ISO 8601, up to 5 years). Defaults to 90 days from now if omitted. Dates in the past are rejected. **Typical rotation workflow:** 1. Call this endpoint to get a new token (optionally with a custom `grace_period_minutes`). 2. Deploy the new token to your systems. 3. The old token continues working for `grace_period_minutes` (if grace period is enabled). 4. After the grace period, the old token is automatically invalidated. ## OpenAPI ````yaml https://rootly-heroku.s3.amazonaws.com/swagger/v1/swagger.json post /v1/api_keys/{id}/rotate openapi: 3.0.1 info: title: Rootly API v1 version: v1 description: >+ # How to generate an API Key? - **Organization dropdown** > **Organization Settings** > **API Keys** # JSON:API Specification Rootly is using **JSON:API** (https://jsonapi.org) specification: - JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. - JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability. - JSON:API requires use of the JSON:API media type (**application/vnd.api+json**) for exchanging data. # Authentication and Requests We use standard HTTP Authentication over HTTPS to authorize your requests. ``` curl --request GET \ --header 'Content-Type: application/vnd.api+json' \ --header 'Authorization: Bearer YOUR-TOKEN' \ --url https://api.rootly.com/v1/incidents ```
# Rate limiting - There is a default limit of **5** **GET**, **HEAD**, and **OPTIONS** calls **per API key** every **60 seconds** (0 hours). The limit is calculated over a **0-hour sliding window** looking back from the current time. While the limit can be configured to support higher thresholds, you must first contact your **Rootly Customer Success Manager** to make any adjustments. - There is a default limit of **3** **POST**, **PUT**, **PATCH** or **DELETE** calls **per API key** every **60 seconds** (0 hours). The limit is calculated over a **0-hour sliding window** looking back from the current time. While the limit can be configured to support higher thresholds, you must first contact your **Rootly Customer Success Manager** to make any adjustments. - When rate limits are exceeded, the API will return a **429 Too Many Requests** HTTP status code with the response: `{"error": "Rate limit exceeded. Try again later."}` - **X-RateLimit headers** are included in every API response, providing real-time rate limit information: - **X-RateLimit-Limit** - The maximum number of requests permitted and the time window (e.g., "1000, 1000;window=3600" for 1000 requests per hour) - **X-RateLimit-Remaining** - The number of requests remaining in the current rate limit window - **X-RateLimit-Used** - The number of requests already made in the current window - **X-RateLimit-Reset** - The time at which the current rate limit window resets, in UTC epoch seconds # Pagination - Pagination is supported for all endpoints that return a collection of items. - Pagination is controlled by the **page** query parameter ## Example ``` curl --request GET \ --header 'Content-Type: application/vnd.api+json' \ --header 'Authorization: Bearer YOUR-TOKEN' \ --url https://api.rootly.com/v1/incidents?page[number]=1&page[size]=10 ``` x-logo: url: https://rootly-heroku.s3.us-east-1.amazonaws.com/swagger/v1/logo.png servers: - url: https://api.rootly.com security: [] paths: /v1/api_keys/{id}/rotate: parameters: - name: id in: path required: true schema: type: string post: tags: - API Keys summary: Rotate an API key description: > Rotate an API key's token. Issues a new secret token and returns it — **the new token is only shown once**, so store it securely. **Self-only:** You can only rotate the API key that was used to authenticate this request. Attempting to rotate a different key returns `403 Forbidden`. **Grace period:** When enabled for your organization, the previous token remains valid after rotation, giving you time to deploy the new token without downtime. Pass `grace_period_minutes` (integer, 0–1440, default 30) to control how long the old token stays valid. Set to 0 to immediately invalidate the old token. The `grace_period_ends_at` field in the response confirms the exact time the old token will stop working. **Expiration:** Optionally provide a new `expires_at` date (ISO 8601, up to 5 years). Defaults to 90 days from now if omitted. Dates in the past are rejected. **Typical rotation workflow:** 1. Call this endpoint to get a new token (optionally with a custom `grace_period_minutes`). 2. Deploy the new token to your systems. 3. The old token continues working for `grace_period_minutes` (if grace period is enabled). 4. After the grace period, the old token is automatically invalidated. operationId: rotateApiKey parameters: [] requestBody: content: application/vnd.api+json: schema: $ref: '#/components/schemas/rotate_api_key' responses: '200': description: API key rotated content: application/vnd.api+json: schema: $ref: '#/components/schemas/api_key_with_token_response' '404': description: API key not found content: application/vnd.api+json: schema: $ref: '#/components/schemas/errors_list' security: - bearer_auth: [] components: schemas: rotate_api_key: type: object properties: data: type: object properties: type: type: string enum: - api_keys attributes: type: object properties: expires_at: type: string description: The new expiration date after rotation (ISO 8601) format: date-time nullable: true grace_period_minutes: type: integer description: >- How many minutes to keep the old token valid. Only applies when the grace period feature is enabled for your organization. Defaults to 30. minimum: 0 maximum: 1440 default: 30 additionalProperties: false required: - type - attributes required: - data api_key_with_token_response: type: object properties: data: type: object properties: id: type: string description: Unique ID of the API key type: type: string enum: - api_keys attributes: type: object allOf: - $ref: '#/components/schemas/api_key' - type: object properties: token: type: string description: The API key token (only shown once) required: - token required: - id - type - attributes included: type: array items: $ref: '#/components/schemas/jsonapi_included_resource' required: - data errors_list: type: object properties: errors: type: array items: type: object properties: title: type: string status: type: string code: type: string nullable: true detail: type: string nullable: true required: - title - status api_key: type: object properties: name: type: string description: The name of the API key description: type: string description: A description of the API key nullable: true kind: type: string description: The kind of the API key enum: - personal - team - organization role_id: type: string description: The role ID nullable: true on_call_role_id: type: string description: The on-call role ID nullable: true created_at: type: string description: Date of creation updated_at: type: string description: Date of last update expires_at: type: string description: Expiration date nullable: true last_used_at: type: string description: Date of last use nullable: true grace_period_ends_at: type: string description: Grace period end date nullable: true required: - name - kind - created_at - updated_at jsonapi_included_resource: type: object properties: id: type: string type: type: string attributes: type: object additionalProperties: true relationships: type: object additionalProperties: true required: - id - type securitySchemes: bearer_auth: type: http scheme: bearer ````