Variables and OAuth 2

Where the values of {{name}} come from, and how a request gets a token from an OAuth 2 token endpoint.

Environments and variables

{{name}} is replaced by the variable name. Variables come from, the later winning:

1. the environment files of the request file’s directory or, when it has none, the working directory: http-client.env.json (its $shared object, then the object of --env), http-client.private.env.json (the same), .env and .env.NAME;
2. --env-file files (JSON like http-client.env.json, or KEY=VALUE lines);
3. @name = value lines outside of requests;
4. what scripts set (exports, client.global.set);
5. @name = value lines of the request’s region;
6. --var NAME=VALUE.

Responses of named requests can be used in the requests after them:

Reference	Value
{{list.response.status}}	The status
{{list.response.headers.Location}}	A header
{{list.response.body.$[0].id}}, {{list.response.body./0/id}}	A value of the JSON body (a path or a JSON pointer)
{{list.response.body}}	The body
{{list.id}}	httpYac’s form: a value of the JSON body

Built-in variables: {{$uuid}} (and $guid, $random.uuid), {{$timestamp}}, {{$isoTimestamp}}, {{$datetime iso8601}}, {{$datetime rfc1123}}, {{$randomInt MIN MAX}}, {{$processEnv NAME}} and {{$dotenv NAME}}. A variable that isn’t defined is a warning and stays as it is. \{{ is a literal {{.

Authorization: Basic user:password (or Basic user password) is sent base64-encoded, as httpYac and the JetBrains client do.

OAuth 2

Authorization: oauth2 [GRANT] [PREFIX] gets a token from the token endpoint and sends Authorization: Bearer TOKEN instead, with httpYac’s syntax and variables:

GET {{host}}/pets
Authorization: oauth2 client_credentials

Grant	Sent to the token endpoint
client_credentials (when no grant is written)	The client’s credentials
password	PREFIX_username and PREFIX_password too
refresh_token	PREFIX_refreshToken

The token request is configured by variables named after the prefix (oauth2 when no prefix is written; Authorization: oauth2 password keycloak reads keycloak_tokenEndpoint and so on). They come from environment files, @ variables and --var, like any other variable:

Variable	Meaning
oauth2_tokenEndpoint	The token endpoint’s URL (required)
oauth2_clientId	The client’s id (required)
oauth2_clientSecret	The client’s secret; none for a public client
oauth2_scope	Space-separated scopes
oauth2_audience, oauth2_resource	Sent as audience and resource when set
oauth2_username, oauth2_password	The password grant’s user
oauth2_refreshToken	The refresh_token grant’s refresh token
oauth2_useAuthorizationHeader	true (the default): the client’s id and secret go in a Basic Authorization header; false: in the form
oauth2_issuer	openid only: the token endpoint is read from ISSUER/.well-known/openid-configuration when oauth2_tokenEndpoint isn’t set

Authorization: openid ... is the same, with the OpenID Connect discovery of oauth2_issuer. The token is requested once per run for each configuration (the endpoint, the client, the scopes, the user) and requested again, with its refresh token when it has one, shortly before its expires_in runs out. The token endpoint is reached like any request: https:// is verified as --ca-cert and --insecure say. A token endpoint that refuses fails the request, which isn’t sent:

FAIL GET http://localhost:8080/pets
    no OAuth 2 token: the OAuth 2 token endpoint http://localhost:8080/token answered 401 (invalid_client: unknown client)

The authorization_code (or code), implicit and device_code grants need a browser or a person, and token exchange isn’t supported: those requests are skipped with a warning. Tokens, refresh tokens, client secrets, passwords and the credentials of Authorization headers are shown as [redacted] wherever they would appear: in URLs, errors, assertion messages, script logs, warnings and the reports.