Proxy API

Dev Proxy comes with a web API that allows you to interact with the proxy programmatically. The API is available on the IP address and port specified in the proxy settings.

All API operations require a bearer token. Dev Proxy generates a unique token for each running instance and stores it in a file that's accessible only to the user who started the instance. Get the token using devproxy status or devproxy api token. When the CI environment variable is set, use devproxy api token because Dev Proxy omits the token from status and startup output.

Include the token in the Authorization header:

Authorization: Bearer <token>

Requests without a valid token return 401 Unauthorized. Browser requests must also come from an origin listed in the apiAllowedOrigins setting. Other origins return 403 Forbidden.

Operations

The following list shows available API operations.

GET /proxy

Returns an instance of ProxyInfo with information about the currently running Dev Proxy instance.

Example: Get information about the currently running Dev Proxy instance

Request:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

Response:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy

Controls the currently running Dev Proxy instance.

Example: start recording

Request:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

Response:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Example: stop recording

Request:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

Response:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy/jwtToken

Generates a JSON Web Token (JWT).

Request:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

Note

Registered claims (for example, iss, sub, aud, exp, nbf, iat, jti) are automatically added to the token. If you specify any of these claims in the request, the API ignores the values you provide.

Response:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

POST /proxy/mockrequest

Raises a mock request. Equivalent of pressing w in the console where Dev Proxy is running.

Request:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

Response:

202 Accepted

GET /proxy/rootCertificate?format=crt

Downloads the public key of the root certificate in PEM (Privacy Enhanced Mail) format that Dev Proxy uses to decrypt HTTPS requests. This API is helpful when you want to trust the root certificate on your host while running Dev Proxy in a Docker container.

At this moment, the only supported format is crt. The API returns a 400 Bad Request error if you specify any other format or don't specify a format at all.

Request:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

Response:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

POST /proxy/stopproxy

Gracefully shuts down Dev Proxy.

Request:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

Response:

202 Accepted

Models

ProxyInfo

Information about the currently running Dev Proxy instance.

Property	Type	Description
recording	boolean	Whether the proxy is currently recording requests
configFile	string	Path to the configuration file that Dev Proxy is using (read-only)

JwtOptions

Options for generating a JWT token.

Property	Type	Description
name	string	The name of the user to create the token for
audience	string[]	The audiences to create the token for
issuer	string[]	The issuer of the token
roles	string[]	A role claim to add to the token
scopes	string[]	A scope claim to add to the token
claims	KeyValuePair	Claims to add to the token
validFor	number	The duration (in minutes) for which the token is valid
signingKey	string	The key to use to sign the token. Must be at least 32 characters long. If not specified, uses a randomly generated key.

JwtInfo

Information about a JWT token.

Property	Type	Description
token	string	The JWT token