Authentication Types

hitspec supports 8 authentication methods through the # @auth metadata directive. Instead of manually constructing Authorization headers, declare your auth method and hitspec handles the rest.

Syntax

# @auth <method> <params...>

All parameters support {{variable}} interpolation.

Methods

bearer

Sends an Authorization: Bearer <token> header.

# @auth bearer {{token}}

Parameter	Description
`token`	The bearer token value

Generated header: Authorization: Bearer <token>

basic

Sends a Base64-encoded Authorization: Basic <credentials> header.

# @auth basic {{username}}, {{password}}

Parameter	Description
`username`	Username
`password`	Password

Generated header: Authorization: Basic <base64(username:password)>

apiKey

Sends the API key as a custom request header.

# @auth apiKey X-API-Key, {{apiKey}}

Parameter	Description
`headerName`	Name of the header to set
`value`	API key value

Generated header: <headerName>: <value>

apiKeyQuery

Appends the API key as a URL query parameter.

# @auth apiKeyQuery api_key, {{apiKey}}

Parameter	Description
`paramName`	Query parameter name
`value`	API key value

Effect: Appends ?api_key=<value> to the request URL.

digest

HTTP Digest authentication. hitspec handles the challenge-response handshake automatically.

# @auth digest {{username}}, {{password}}

Parameter	Description
`username`	Username
`password`	Password

aws

Signs requests using AWS Signature Version 4 for AWS services or compatible APIs (e.g., MinIO, LocalStack).

# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}

Parameter	Description
`accessKey`	AWS Access Key ID
`secretKey`	AWS Secret Access Key
`region`	AWS region (e.g., `us-east-1`)
`service`	AWS service name (e.g., `s3`, `execute-api`)

oauth2 client_credentials

Fetches an access token using the OAuth2 Client Credentials grant, then sends it as a Bearer token.

# @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2

Parameter	Required	Description
`tokenUrl`	Yes	OAuth2 token endpoint
`clientId`	Yes	Application client ID
`clientSecret`	Yes	Application client secret
`scopes`	No	Comma-separated list of scopes

oauth2 password

Fetches an access token using the OAuth2 Resource Owner Password Credentials grant.

# @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2

Parameter	Required	Description
`tokenUrl`	Yes	OAuth2 token endpoint
`clientId`	Yes	Application client ID
`clientSecret`	Yes	Application client secret
`username`	Yes	Resource owner username
`password`	Yes	Resource owner password
`scopes`	No	Comma-separated list of scopes

Quick Reference

Method	Syntax	Params
Bearer	`# @auth bearer <token>`	1
Basic	`# @auth basic <user>, <pass>`	2
API Key (Header)	`# @auth apiKey <header>, <value>`	2
API Key (Query)	`# @auth apiKeyQuery <param>, <value>`	2
Digest	`# @auth digest <user>, <pass>`	2
AWS Sig v4	`# @auth aws <key>, <secret>, <region>, <service>`	4
OAuth2 Client Creds	`# @auth oauth2 client_credentials <url>, <id>, <secret>, <scopes>`	3-4
OAuth2 Password	`# @auth oauth2 password <url>, <id>, <secret>, <user>, <pass>, <scopes>`	5-6

Using Auth with Captures

Capture a token from a login response and use it in subsequent requests:

### Login
# @name login

POST {{baseUrl}}/auth/login
Content-Type: application/json

{"email": "test@example.com", "password": "secret"}

>>>capture
token from body.access_token
<<<

### Protected resource
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<

Store credentials in environment variables or hitspec.yaml environments to keep them out of your test files. Reference them with {{$env(VAR)}} or {{variableName}}.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Authentication Types

Syntax

Methods

bearer

basic

apiKey

apiKeyQuery

digest

aws

oauth2 client_credentials

oauth2 password

Quick Reference

Using Auth with Captures

​Syntax

​Methods

​bearer

​basic

​apiKey

​apiKeyQuery

​digest

​aws

​oauth2 client_credentials

​oauth2 password

​Quick Reference

​Using Auth with Captures

Syntax

Methods

bearer

basic

apiKey

apiKeyQuery

digest

aws

oauth2 client_credentials

oauth2 password

Quick Reference

Using Auth with Captures