Secrets - ngrok documentation

Create Secret

Create a new Secret

Request

POST /vault_secrets

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"Database password for prod postgres instance","metadata":"env=prod,service=postgres","name":"db-password","value":"supersecret123","vault_id":"vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7"}' \
https://api.ngrok.com/vault_secrets

Parameters

Name	Type	Description
`name`	string	Name of secret
`value`	string	Value of secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`description`	string	description of Secret
`vault_id`	string	unique identifier of the referenced vault

Response

Returns a 201 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:43Z",
  "created_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "description": "Database password for prod postgres instance",
  "id": "secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "last_updated_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "metadata": "env=prod,service=postgres",
  "name": "db-password",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "vault": {
    "id": "vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7",
    "uri": "https://api.ngrok.com/vaults/vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7"
  }
}

Fields

Name	Type	Description
`id`	string	identifier for Secret
`uri`	string	URI of this Secret API resource
`created_at`	string	Timestamp when the Secret was created (RFC 3339 format)
`updated_at`	string	Timestamp when the Secret was last updated (RFC 3339 format)
`name`	string	Name of secret
`description`	string	description of Secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`created_by`	Ref	Reference to who created this Secret
`last_updated_by`	Ref	Reference to who created this Secret
`vault`	Ref	Reference to the vault the secret is stored in

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Update Secret

Update an existing Secret by ID

Request

PATCH /vault_secrets/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\", \"service\": \"postgres\"}","value":"supersecretupdated"}' \
https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E

Parameters

Name	Type	Description
`id`	string	identifier for Secret
`name`	string	Name of secret
`value`	string	Value of secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`description`	string	description of Secret

Response

Returns a 200 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:43Z",
  "created_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "description": "Database password for prod postgres instance",
  "id": "secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "last_updated_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "metadata": "{\"environment\": \"production\", \"service\": \"postgres\"}",
  "name": "db-password",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "vault": {
    "id": "vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7",
    "uri": "https://api.ngrok.com/vaults/vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7"
  }
}

Fields

Name	Type	Description
`id`	string	identifier for Secret
`uri`	string	URI of this Secret API resource
`created_at`	string	Timestamp when the Secret was created (RFC 3339 format)
`updated_at`	string	Timestamp when the Secret was last updated (RFC 3339 format)
`name`	string	Name of secret
`description`	string	description of Secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`created_by`	Ref	Reference to who created this Secret
`last_updated_by`	Ref	Reference to who created this Secret
`vault`	Ref	Reference to the vault the secret is stored in

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete Secret

Delete a Secret

Request

DELETE /vault_secrets/{id}

Example Request

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

Response

Returns a 204 response with no body on success

Get Secret

Get a Secret by ID

Request

GET /vault_secrets/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E

Response

Returns a 200 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:43Z",
  "created_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "description": "Database password for prod postgres instance",
  "id": "secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "last_updated_by": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "metadata": "env=prod,service=postgres",
  "name": "db-password",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
  "vault": {
    "id": "vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7",
    "uri": "https://api.ngrok.com/vaults/vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7"
  }
}

Fields

Name	Type	Description
`id`	string	identifier for Secret
`uri`	string	URI of this Secret API resource
`created_at`	string	Timestamp when the Secret was created (RFC 3339 format)
`updated_at`	string	Timestamp when the Secret was last updated (RFC 3339 format)
`name`	string	Name of secret
`description`	string	description of Secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`created_by`	Ref	Reference to who created this Secret
`last_updated_by`	Ref	Reference to who created this Secret
`vault`	Ref	Reference to the vault the secret is stored in

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

List Secrets

List all Secrets owned by account

Request

GET /vault_secrets

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "next_page_uri": null,
  "secrets": [
    {
      "created_at": "2025-09-04T10:11:43Z",
      "created_by": {
        "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
        "uri": ""
      },
      "description": "Database password for prod postgres instance",
      "id": "secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
      "last_updated_by": {
        "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
        "uri": ""
      },
      "metadata": "env=prod,service=postgres",
      "name": "db-password",
      "updated_at": "2025-09-04T10:11:43Z",
      "uri": "https://api.ngrok.com/vault_secrets/secret_32ELIJG8pybfIzK6EGVZ3HWrk1E",
      "vault": {
        "id": "vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7",
        "uri": "https://api.ngrok.com/vaults/vault_32ELIFtgRqQ13kcDvI8Bu4y0Ra7"
      }
    }
  ],
  "uri": "https://api.ngrok.com/vault_secrets"
}

Fields

Name	Type	Description
`secrets`	Secret	The list of Secrets for this account
`uri`	string
`next_page_uri`	string	URI of the next page of results, or null if there is no next page

Secret fields

Name	Type	Description
`id`	string	identifier for Secret
`uri`	string	URI of this Secret API resource
`created_at`	string	Timestamp when the Secret was created (RFC 3339 format)
`updated_at`	string	Timestamp when the Secret was last updated (RFC 3339 format)
`name`	string	Name of secret
`description`	string	description of Secret
`metadata`	string	Arbitrary user-defined metadata for this Secret
`created_by`	Ref	Reference to who created this Secret
`last_updated_by`	Ref	Reference to who created this Secret
`vault`	Ref	Reference to the vault the secret is stored in

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Universal Gateway

Traffic Policy

Secure Tunnels

Observability

IAM

SSH Certificates

Partners

​Create Secret

​Request

​Example Request

​Parameters

​Response

​Example Response

​Fields

​Ref fields

​Update Secret

​Request

​Example Request

​Parameters

​Response

​Example Response

​Fields

​Ref fields

​Delete Secret

​Request

​Example Request

​Response

​Get Secret

​Request

​Example Request

​Response

​Example Response

​Fields

​Ref fields

​List Secrets

​Request

​Example Request

​Response

​Example Response

​Fields

​Secret fields

​Ref fields

Create Secret

Request

Example Request

Parameters

Response

Example Response

Fields

Ref fields

Update Secret

Request

Example Request

Parameters

Response

Example Response

Fields

Ref fields

Delete Secret

Request

Example Request

Response

Get Secret

Request

Example Request

Response

Example Response

Fields

Ref fields

List Secrets

Request

Example Request

Response

Example Response

Fields

Secret fields

Ref fields