Amazon API Gateway REST API Reference


Creates a new ApiKey resource to represent an API key.

HTTP Request

POST /apikeys

Request Body

  "name" : "String",
  "description" : "String",
  "enabled" : "Boolean",
  "generateDistinctId" : "Boolean",
  "value" : "String",
  "stageKeys" : [ {
    "restApiId" : "String",
    "stageName" : "String"
  } ],
  "customerId" : "String",
  "tags" : {
    "String" : "String"

Request Body Fields

The request accepts the following fields in JSON format.

  • name
  • The name of the ApiKey.

  • description
  • The description of the ApiKey.

  • enabled
  • Specifies whether the ApiKey can be used by callers.

  • generateDistinctId
  • Specifies whether (true) or not (false) the key identifier is distinct from the created API key value. This parameter is deprecated and should not be used.

  • value
  • Specifies a value of the API key.

  • stageKeys
  • DEPRECATED FOR USAGE PLANS - Specifies stages associated with the API key.

    • restApiId
    • The string identifier of the associated RestApi.

    • stageName
    • The stage name associated with the stage key.

  • customerId
  • An AWS Marketplace customer identifier , when integrating with the AWS SaaS Marketplace.

  • tags
  • The key-value map of strings. The valid character set is [a-zA-Z+-=._:/]. The tag key can be up to 128 characters and must not start with aws:. The tag value can be up to 256 characters.




Error Codes

The following exception may be thrown when the request fails.

  • UnauthorizedException
  • NotFoundException
  • TooManyRequestsException
  • LimitExceededException
  • BadRequestException

For detailed error code information, including the corresponding HTTP Status Codes, see API Gateway Error Codes

Example: Creates an API key


POST /apikeys HTTP/1.1
Content-Type: application/json
X-Amz-Date: 20170223T222156Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

  "name" : "my_api_key",
  "description" : "My API key",
  "enabled" : "false",
  "stageKeys" : [ {
    "restApiId" : "uycll6xg9a",
    "stageName" : "beta"
  } ]

The successful response returns 201 Created status code and a payload similar to the following:

  "_links": {
    "curies": {
      "href": "{rel}.html",
      "name": "apikey",
      "templated": true
    "self": {
      "href": "/apikeys/a2TprUZuzf2EKbbmMUotDaHYGg8kgxFypcarGved"
    "apikey:delete": {
      "href": "/apikeys/a2TprUZuzf2EKbbmMUotDaHYGg8kgxFypcarGved"
    "apikey:update": {
      "href": "/apikeys/a2TprUZuzf2EKbbmMUotDaHYGg8kgxFypcarGved"
  "createdDate": "2016-06-08T22:21:56Z",
  "description": "My API key",
  "enabled": false,
  "id": "a2TprUZuzf2EKbbmMUotDaHYGg8kgxFypcarGved",
  "lastUpdatedDate": "2016-06-08T22:21:56Z",
  "name": "my_api_key",
  "stageKeys": "uycll6xg9a/beta"

See Also