Automate Bot User creation and management with our new APIs | ngrok blog

A little over a year ago, ngrok introduced the idea of Bot Users inside your account. They are sometimes referred to as service accounts, but they become useful as you build more and more integrations with the ngrok platform. Attaching the credentials to a Bot User means that the integration will continue to function as users leave and join your account.

Since all credentials in the ngrok platform need to belong to someone, Bot Users allow you to create credentials that stick around after a user leaves your organization. Another use case for Bot Users that we have seen is to organize and keep track of ngrok usage by our customers’ customers. ngrok is widely adopted by enterprises such as Databricks to securely connect to their customer environments without setting up site-to-site VPNs, private link, or asking them to open inbound ports on their firewall. These customers of ours create a new Bot User for each of their customer integrations.

Today, we are introducing a new API that allows our customers to automate the creation and management of Bot Users in their account. This allows our users to create onboarding scripts and bootstrapping processes that do not require manually creating the Bot User beforehand.

Get started with Bot UsersCopy link to clipboard

Bot Users are available to all ngrok accounts and do not count against any user limits. To create your first Bot User, all you need to do is make sure you have a valid ngrok API token (which can be generated in the ngrok Dashboard) and provide a name.

curl --location 'https://api.ngrok.com/bot_users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer NGROK_API_KEY' \
--data '{ "name":"new Bot User from API" }'

201 Created
{
  "id": "bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi",
  "uri": "https://api.ngrok.com/bot_users/bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi",
  "name": "new Bot User from API",
  "active": true,
  "created_at": "2024-04-23T20:17:08Z"
}

By default, the new Bot User is marked as active. This means that any credentials you assign to it will also be active. Deactivating a Bot User will keep the Bot User and credentials in the system, but not allow them to be used. It is a great way to test what might break before fully deleting the Bot User and credentials.

You can now use the ID of this new Bot User as the `owner_id` when creating a new credential.

curl --location 'https://api.ngrok.com/api_keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer NGROK_API_KEY' \
--data '{
    "description": "ad-hoc dev testing",
    "metadata": "{\"environment\":\"dev\"}",
    "owner_id": "bot_2fW66mP7xeNvV7mOTPVceqBOkWu"
}'

{
   "id": "ak_2fYynCkWGFbxu5mOal6i8K4NtzN",
   "uri": "https://api.ngrok.com/api_keys/ak_2fYynCkWGFbxu5mOal6i8K4NtzN",
   "description": "ad-hoc dev testing",
   "metadata": "{\"environment\":\"dev\"}",
   "created_at": "2024-04-24T21:01:10Z",
   "token": "REDACTED",
   "owner_id": "bot_2fW66mP7xeNvV7mOTPVceqBOkWu"
}

Update and delete Bot UsersCopy link to clipboard

Similarly, you can update the name and active/inactive status of an existing Bot User using the `PATCH` method. This is useful for any situations where you need to temporarily block the usage of all of the bot’s credentials to see what breaks.

curl --location --request PATCH 'https://api.ngrok.com/bot_users/bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer NGROK_API_KEY' \
--data '{
    "active": false
}'

200 OK
{
    "id": "bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi",
    "uri": "https://api.ngrok.com/bot_users/bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi",
    "name": "new Bot User from API",
    "active": false,
    "created_at": "2024-04-23T20:17:08Z"
}

Finally, you can automate deprovisioning of Bot Users leveraging the DELETE method.

curl --location --request DELETE 'https://api.ngrok.com/bot_users/bot_2fW4JZ4hIr5NaXOUh1Je7SIUahi' \
--header 'Authorization: Bearer NGROK_API_KEY'

204 No Content

Try out Bot Users in your ngrok accountCopy link to clipboard

Our new Bot Users API delivers on many customers’ requests to help automate the management of credentials for their accounts. We always recommend creating unique credentials for each 3rd party integration or customer that is using your ngrok account, and now this can be completely automated using your favorite scripting language.

This update will make its way into the ngrok client SDKs in the coming weeks, and you will be able to easily call this endpoint from your favorite programming language.

Give it a go! If you have any questions or feedback for the team, please jump into our community Slack or reach out to our support team. And, if you don’t have an account, you can sign up today to get started with ngrok.