Skip to Content

Create a temporary API key

POSThttps://api.respan.ai/api/temporary-keys/

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
-
name string Optional
Key name.
Example: "Production Key"
expiry_date string Optional
Expiry date (ISO 8601).
Format: date-time
Example: "2025-12-31T23:59:59Z"
max_usage integer Optional
Max usage count. -1 = unlimited.
Default: -1
Example: -1
rate_limit integer Optional
Calls per minute. Overridden by plan limit.
spending_limit number Optional
Spending limit in USD for gateway usage.
is_test boolean Optional
Test key (true) or production key (false).
Default: false
limit_policies array<object> Optional
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.
limit_policies[] object Array item
A cost, token, or request cap created with the API key and scoped to it. Once the cap is reached, gateway requests with the key get 429.
Reference: #/components/schemas/APIKeyLimitPolicySpec
limit_policies[].max_value number Required in parent
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.
limit_policies[].metric string Optional
What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.
Allowed: "cost", "request_count", "token_count"
Default: cost
limit_policies[].period string Required in parent
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.
limit_policies[].warning_threshold number or null Optional
Optional soft threshold; must be strictly below max_value. Fires an alert without blocking.
limit_policies[].name string Optional
Display label. When blank, the dashboard falls back to the key’s own name.
Default: “
limit_policies[].notification_method_id string or null Optional
OrganizationNotificationMethod id to ping when a rule trips. Must belong to the same project.

OpenAPI request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Key name.",
      "example": "Production Key"
    },
    "expiry_date": {
      "type": "string",
      "format": "date-time",
      "description": "Expiry date (ISO 8601).",
      "example": "2025-12-31T23:59:59Z"
    },
    "max_usage": {
      "type": "integer",
      "description": "Max usage count. -1 = unlimited.",
      "default": -1,
      "example": -1
    },
    "rate_limit": {
      "type": "integer",
      "description": "Calls per minute. Overridden by plan limit."
    },
    "spending_limit": {
      "type": "number",
      "description": "Spending limit in USD for gateway usage."
    },
    "is_test": {
      "type": "boolean",
      "description": "Test key (`true`) or production key (`false`).",
      "default": false
    },
    "limit_policies": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/APIKeyLimitPolicySpec"
      },
      "description": "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`."
    }
  }
}

Responses

201

Created API key.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
id string Optional
API key ID.
name string Optional
Key name.
prefix string Optional
Key prefix.
is_test boolean Optional
Test or production key.
expiry_date string Optional
Expiry date.
Format: date-time
max_usage integer Optional
Max usage count. -1 = unlimited.
rate_limit number or null Optional
Requests per minute. null uses the organization default.
spending_limit number or null Optional
Spending limit in USD. null when not set.
api_key string Optional
The API key value. Only returned on creation - store it securely.
Example: "vcjRcdm8.5hSZiXrA698O6KAiWX5CJj8Zrbp0H6gV"
key_usage integer Optional
Number of times this key has been used.
Example: 0
created string Optional
When the API key was created.
Format: date-time
unique_organization_id string or null Optional
Owning organization UUID.

OpenAPI response schema

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

400

Validation failed, for example an invalid limit policy.

application/json

Field Type Requirement Description and constraints
$ object Body
Maps each invalid field to its error messages.
$.<key> any Map value
-

OpenAPI response schema

{
  "type": "object",
  "description": "Maps each invalid field to its error messages.",
  "additionalProperties": {}
}
Example
JSON
{ "limit_policies": [ { "warning_threshold": [ "warning_threshold (20.0) must be strictly below max_value (10.0); a warning at or above the cap can never fire before the cap blocks." ] } ] }

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Create a temporary API key",
  "operationId": "createApiKey",
  "tags": [
    "Temporary API Keys"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Key name.",
              "example": "Production Key"
            },
            "expiry_date": {
              "type": "string",
              "format": "date-time",
              "description": "Expiry date (ISO 8601).",
              "example": "2025-12-31T23:59:59Z"
            },
            "max_usage": {
              "type": "integer",
              "description": "Max usage count. -1 = unlimited.",
              "default": -1,
              "example": -1
            },
            "rate_limit": {
              "type": "integer",
              "description": "Calls per minute. Overridden by plan limit."
            },
            "spending_limit": {
              "type": "number",
              "description": "Spending limit in USD for gateway usage."
            },
            "is_test": {
              "type": "boolean",
              "description": "Test key (`true`) or production key (`false`).",
              "default": false
            },
            "limit_policies": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/APIKeyLimitPolicySpec"
              },
              "description": "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`."
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Created API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "API key ID."
              },
              "name": {
                "type": "string",
                "description": "Key name."
              },
              "prefix": {
                "type": "string",
                "description": "Key prefix."
              },
              "is_test": {
                "type": "boolean",
                "description": "Test or production key."
              },
              "expiry_date": {
                "type": "string",
                "format": "date-time",
                "description": "Expiry date."
              },
              "max_usage": {
                "type": "integer",
                "description": "Max usage count. -1 = unlimited."
              },
              "rate_limit": {
                "type": "number",
                "nullable": true,
                "description": "Requests per minute. null uses the organization default."
              },
              "spending_limit": {
                "type": "number",
                "description": "Spending limit in USD. `null` when not set.",
                "nullable": true
              },
              "api_key": {
                "type": "string",
                "description": "The API key value. Only returned on creation - store it securely.",
                "example": "vcjRcdm8.5hSZiXrA698O6KAiWX5CJj8Zrbp0H6gV"
              },
              "key_usage": {
                "type": "integer",
                "description": "Number of times this key has been used.",
                "example": 0
              },
              "created": {
                "type": "string",
                "format": "date-time",
                "description": "When the API key was created."
              },
              "unique_organization_id": {
                "type": "string",
                "nullable": true,
                "description": "Owning organization UUID."
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "400": {
      "description": "Validation failed, for example an invalid limit policy.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "description": "Maps each invalid field to its error messages.",
            "additionalProperties": {}
          },
          "example": {
            "limit_policies": [
              {
                "warning_threshold": [
                  "warning_threshold (20.0) must be strictly below max_value (10.0); a warning at or above the cap can never fire before the cap blocks."
                ]
              }
            ]
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "schemas": {
    "APIKeyLimitPolicySpec": {
      "type": "object",
      "required": [
        "max_value",
        "period"
      ],
      "description": "A cost, token, or request cap created with the API key and scoped to it. Once the cap is reached, gateway requests with the key get `429`.",
      "properties": {
        "max_value": {
          "type": "number",
          "description": "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": {
          "type": "string",
          "enum": [
            "cost",
            "request_count",
            "token_count"
          ],
          "default": "cost",
          "description": "What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls."
        },
        "period": {
          "type": "string",
          "description": "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": {
          "type": "number",
          "nullable": true,
          "description": "Optional soft threshold; must be strictly below `max_value`. Fires an alert without blocking."
        },
        "name": {
          "type": "string",
          "default": "",
          "description": "Display label. When blank, the dashboard falls back to the key's own name."
        },
        "notification_method_id": {
          "type": "string",
          "nullable": true,
          "description": "OrganizationNotificationMethod id to ping when a rule trips. Must belong to the same project."
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}