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 \
-X POST \
-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

description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes
owner_id	string	If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Response

Returns a 201 response on success

Example Response

{
	"id": "ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"uri": "https://api.ngrok.com/api_keys/ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"description": "ad-hoc dev testing",
	"metadata": "{\"environment\":\"dev\"}",
	"created_at": "2023-10-25T22:19:22Z",
	"token": "2XH3pnooyvtQhXolHnE1Gd4mOEf_76fiktTrjN1h4jZBmWnHd",
	"owner_id": "usr_2XH3pmHJqhurkscM3W3eN8WUxKd"
}

Fields

id	string	unique API key resource identifier
uri	string	URI to the API resource of this API key
description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at	string	timestamp when the api key was created, RFC 3339 format
token	string	the 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.
owner_id	string	If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Delete API Key

Delete an API key by ID

Request

DELETE /api_keys/{id}

Example Request

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

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 \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys/ak_2XH3pnooyvtQhXolHnE1Gd4mOEf

Response

Returns a 200 response on success

Example Response

{
	"id": "ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"uri": "https://api.ngrok.com/api_keys/ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"description": "ad-hoc dev testing",
	"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
	"created_at": "2023-10-25T22:19:22Z",
	"token": null,
	"owner_id": "usr_2XH3pmHJqhurkscM3W3eN8WUxKd"
}

Fields

id	string	unique API key resource identifier
uri	string	URI to the API resource of this API key
description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at	string	timestamp when the api key was created, RFC 3339 format
token	string	the 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.
owner_id	string	If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

List API Keys

List all API keys owned by this account

Request

GET /api_keys

Example Request

curl \
-X GET \
-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_2XH3pjVBvImhjflDACK7ezpMXIX",
			"uri": "https://api.ngrok.com/api_keys/ak_2XH3pjVBvImhjflDACK7ezpMXIX",
			"description": "api key for example generation",
			"created_at": "2023-10-25T22:19:22Z",
			"token": null,
			"owner_id": "usr_2XH3pmHJqhurkscM3W3eN8WUxKd"
		},
		{
			"id": "ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
			"uri": "https://api.ngrok.com/api_keys/ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
			"description": "ad-hoc dev testing",
			"metadata": "{\"environment\":\"dev\"}",
			"created_at": "2023-10-25T22:19:22Z",
			"token": null,
			"owner_id": "usr_2XH3pmHJqhurkscM3W3eN8WUxKd"
		}
	],
	"uri": "https://api.ngrok.com/api_keys",
	"next_page_uri": null
}

Fields

keys	APIKey	the list of API keys for this account
uri	string	URI of the API keys list API resource
next_page_uri	string	URI of the next page, or null if there is no next page

APIKey fields

id	string	unique API key resource identifier
uri	string	URI to the API resource of this API key
description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at	string	timestamp when the api key was created, RFC 3339 format
token	string	the 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.
owner_id	string	If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Update API Key

Update attributes of an API key by ID.

Request

PATCH /api_keys/{id}

Example Request

curl \
-X PATCH \
-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_2XH3pnooyvtQhXolHnE1Gd4mOEf

Parameters

id	string
description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response

{
	"id": "ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"uri": "https://api.ngrok.com/api_keys/ak_2XH3pnooyvtQhXolHnE1Gd4mOEf",
	"description": "ad-hoc dev testing",
	"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
	"created_at": "2023-10-25T22:19:22Z",
	"token": null,
	"owner_id": "usr_2XH3pmHJqhurkscM3W3eN8WUxKd"
}

Fields

id	string	unique API key resource identifier
uri	string	URI to the API resource of this API key
description	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata	string	arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at	string	timestamp when the api key was created, RFC 3339 format
token	string	the 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.
owner_id	string	If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.