Skip to main content

API Keys


Create API Key

Create a new API key. The generated API key can be used to authenticate to the ngrok API.

Request

POST /api_keys

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"ad-hoc dev testing","metadata":"{\"environment\":\"dev\"}"}' \
https://api.ngrok.com/api_keys

Parameters

   
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 201 response on success

Example Response

{
"id": "ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"uri": "https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"description": "ad-hoc dev testing",
"metadata": "{\"environment\":\"dev\"}",
"created_at": "2022-11-29T20:07:20Z",
"token": "2IEh2GqvJ4Z0KodqLgHwkOdZivN_5bYNaetVzTcyK8HwF9NhL"
}

Fields

   
idstringunique API key resource identifier
uristringURI to the API resource of this API key
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes
created_atstringtimestamp when the api key was created, RFC 3339 format
tokenstringthe bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

Delete API Key

Delete an API key by ID

Request

DELETE /api_keys/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN

Response

Returns a 204 response with no body on success

Get API Key

Get the details of an API key by ID.

Request

GET /api_keys/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN

Response

Returns a 200 response on success

Example Response

{
"id": "ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"uri": "https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"description": "ad-hoc dev testing",
"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
"created_at": "2022-11-29T20:07:20Z",
"token": null
}

Fields

   
idstringunique API key resource identifier
uristringURI to the API resource of this API key
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes
created_atstringtimestamp when the api key was created, RFC 3339 format
tokenstringthe bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

List API Keys

List all API keys owned by this account

Request

GET /api_keys

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys

Response

Returns a 200 response on success

Example Response

{
"keys": [
{
"id": "ak_2IEh26zpFo4FlTEb23xAddnpVQD",
"uri": "https://api.ngrok.com/api_keys/ak_2IEh26zpFo4FlTEb23xAddnpVQD",
"description": "api key for example generation",
"created_at": "2022-11-29T20:07:19Z",
"token": null
},
{
"id": "ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"uri": "https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"description": "ad-hoc dev testing",
"metadata": "{\"environment\":\"dev\"}",
"created_at": "2022-11-29T20:07:20Z",
"token": null
}
],
"uri": "https://api.ngrok.com/api_keys",
"next_page_uri": null
}

Fields

   
keysAPIKeythe list of API keys for this account
uristringURI of the API keys list API resource
next_page_uristringURI of the next page, or null if there is no next page

APIKey fields

   
idstringunique API key resource identifier
uristringURI to the API resource of this API key
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes
created_atstringtimestamp when the api key was created, RFC 3339 format
tokenstringthe bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

Update API Key

Update attributes of an API key by ID.

Request

PATCH /api_keys/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\":\"dev\", \"owner_id\": 123}"}' \
https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN

Parameters

   
idstring
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response

{
"id": "ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"uri": "https://api.ngrok.com/api_keys/ak_2IEh2GqvJ4Z0KodqLgHwkOdZivN",
"description": "ad-hoc dev testing",
"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
"created_at": "2022-11-29T20:07:20Z",
"token": null
}

Fields

   
idstringunique API key resource identifier
uristringURI to the API resource of this API key
descriptionstringhuman-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadatastringarbitrary user-defined data of this API key. optional, max 4096 bytes
created_atstringtimestamp when the api key was created, RFC 3339 format
tokenstringthe bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.