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
Name | Type | Description |
---|---|---|
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
{
"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
Name | Type | Description |
---|---|---|
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_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
Name | Type | Description |
---|---|---|
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": [
{
"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
Name | Type | Description |
---|---|---|
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
Name | Type | Description |
---|---|---|
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_2hrGw25xR00AovPe2eBnjyGDdAt
Parameters
Name | Type | Description |
---|---|---|
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
{
"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
Name | Type | Description |
---|---|---|
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. |