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_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "uri": "https://api.ngrok.com/api_keys/ak_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "description": "ad-hoc dev testing",
    "metadata": "{\"environment\":\"dev\"}",
    "created_at": "2023-07-31T23:17:17Z",
    "token": "2TMGGAPsoyLDT8RSW6nOJVYcwIc_29sUdWYYXTdSxvEoqJmmP",
    "owner_id": "usr_2TMGG635o87KDP13PBjUDx2rzJY"
}

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_2TMGGAPsoyLDT8RSW6nOJVYcwIc

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_2TMGGAPsoyLDT8RSW6nOJVYcwIc

Response

Returns a 200 response on success

Example Response

{
    "id": "ak_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "uri": "https://api.ngrok.com/api_keys/ak_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "description": "ad-hoc dev testing",
    "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
    "created_at": "2023-07-31T23:17:17Z",
    "token": null,
    "owner_id": "usr_2TMGG635o87KDP13PBjUDx2rzJY"
}

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_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
            "uri": "https://api.ngrok.com/api_keys/ak_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
            "description": "ad-hoc dev testing",
            "metadata": "{\"environment\":\"dev\"}",
            "created_at": "2023-07-31T23:17:17Z",
            "token": null,
            "owner_id": "usr_2TMGG635o87KDP13PBjUDx2rzJY"
        },
        {
            "id": "ak_2TMGGAW303F8jsFNPiDNMvvIA3F",
            "uri": "https://api.ngrok.com/api_keys/ak_2TMGGAW303F8jsFNPiDNMvvIA3F",
            "description": "api key for example generation",
            "created_at": "2023-07-31T23:17:17Z",
            "token": null,
            "owner_id": "usr_2TMGG635o87KDP13PBjUDx2rzJY"
        }
    ],
    "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_2TMGGAPsoyLDT8RSW6nOJVYcwIc

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_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "uri": "https://api.ngrok.com/api_keys/ak_2TMGGAPsoyLDT8RSW6nOJVYcwIc",
    "description": "ad-hoc dev testing",
    "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
    "created_at": "2023-07-31T23:17:17Z",
    "token": null,
    "owner_id": "usr_2TMGG635o87KDP13PBjUDx2rzJY"
}

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.

API Keys

Create API Key​

Request​

Example Request​

Parameters​

Response​

Example Response​

Fields​

Delete API Key​

Request​

Example Request​

Response​

Get API Key​

Request​

Example Request​

Response​

Example Response​

Fields​

List API Keys​

Request​

Example Request​

Response​

Example Response​

Fields​

APIKey fields​

Update API Key​

Request​

Example Request​

Parameters​

Response​

Example Response​

Fields​

Create API Key

Request

Example Request

Parameters

Response

Example Response

Fields

Delete API Key

Request

Example Request

Response

Get API Key

Request

Example Request

Response

Example Response

Fields

List API Keys

Request

Example Request

Response

Example Response

Fields

APIKey fields

Update API Key

Request

Example Request

Parameters

Response

Example Response

Fields