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

NameTypeDescription
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
owner_idstringIf 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

{
"created_at": "2024-06-14T06:03:37Z",
"description": "ad-hoc dev testing",
"id": "ak_2hrGw25xR00AovPe2eBnjyGDdAt",
"metadata": "{\"environment\":\"dev\"}",
"owner_id": "usr_2hrGw33K0y2LziI8zHGX8ilMTYX",
"token": "2hrGw25xR00AovPe2eBnjyGDdAt_2mBNvXGkkXLdVSzHFmvU1",
"uri": "https://api.ngrok.com/api_keys/ak_2hrGw25xR00AovPe2eBnjyGDdAt"
}

Fields

NameTypeDescription
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.
owner_idstringIf 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_2hrGw25xR00AovPe2eBnjyGDdAt

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_2hrGw25xR00AovPe2eBnjyGDdAt

Response

Returns a 200 response on success

Example Response

{
"created_at": "2024-06-14T06:03:37Z",
"description": "ad-hoc dev testing",
"id": "ak_2hrGw25xR00AovPe2eBnjyGDdAt",
"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
"owner_id": "usr_2hrGw33K0y2LziI8zHGX8ilMTYX",
"token": null,
"uri": "https://api.ngrok.com/api_keys/ak_2hrGw25xR00AovPe2eBnjyGDdAt"
}

Fields

NameTypeDescription
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.
owner_idstringIf 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": [
{
"created_at": "2024-06-14T06:03:37Z",
"description": "ad-hoc dev testing",
"id": "ak_2hrGw25xR00AovPe2eBnjyGDdAt",
"metadata": "{\"environment\":\"dev\"}",
"owner_id": "usr_2hrGw33K0y2LziI8zHGX8ilMTYX",
"token": null,
"uri": "https://api.ngrok.com/api_keys/ak_2hrGw25xR00AovPe2eBnjyGDdAt"
},
{
"created_at": "2024-06-14T06:03:37Z",
"description": "api key for example generation",
"id": "ak_2hrGw6IN8LBtXlGX1BXAwWUARUD",
"owner_id": "usr_2hrGw33K0y2LziI8zHGX8ilMTYX",
"token": null,
"uri": "https://api.ngrok.com/api_keys/ak_2hrGw6IN8LBtXlGX1BXAwWUARUD"
}
],
"next_page_uri": null,
"uri": "https://api.ngrok.com/api_keys"
}

Fields

NameTypeDescription
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

NameTypeDescription
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.
owner_idstringIf 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_2hrGw25xR00AovPe2eBnjyGDdAt

Parameters

NameTypeDescription
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

{
"created_at": "2024-06-14T06:03:37Z",
"description": "ad-hoc dev testing",
"id": "ak_2hrGw25xR00AovPe2eBnjyGDdAt",
"metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
"owner_id": "usr_2hrGw33K0y2LziI8zHGX8ilMTYX",
"token": null,
"uri": "https://api.ngrok.com/api_keys/ak_2hrGw25xR00AovPe2eBnjyGDdAt"
}

Fields

NameTypeDescription
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.
owner_idstringIf 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.