Authentication for API tests (@auth)

hitspec supports 8 authentication methods through the @auth metadata directive. Instead of manually setting Authorization headers, declare your auth strategy once per request and hitspec handles the rest.

Bearer Token

The most common method for API authentication. Sends an Authorization: Bearer <token> header.

### Access protected resource
# @name getProfile
# @auth bearer {{token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<

Basic Auth

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

### Login with Basic Auth
# @name basicLogin
# @auth basic {{username}}, {{password}}

GET {{baseUrl}}/admin/dashboard

>>>
expect status 200
<<<

API Key (Header)

Sends the API key as a custom request header. Specify the header name and value.

### Access with API key in header
# @name apiKeyRequest
# @auth apiKey X-API-Key, {{apiKey}}

GET {{baseUrl}}/data

>>>
expect status 200
<<<

API Key (Query String)

Appends the API key as a query parameter instead of a header.

### Access with API key in query string
# @name apiKeyQueryRequest
# @auth apiKeyQuery api_key, {{apiKey}}

GET {{baseUrl}}/data

>>>
expect status 200
<<<

Digest Auth

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

### Digest auth request
# @name digestRequest
# @auth digest {{username}}, {{password}}

GET {{baseUrl}}/secure/resource

>>>
expect status 200
<<<

AWS Signature v4

Signs requests using AWS Signature Version 4 for authenticating with AWS services or compatible APIs.

### AWS signed request
# @name awsRequest
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}

GET https://{{service}}.{{region}}.amazonaws.com/resource

>>>
expect status 200
<<<

The parameters are:

Access Key ID - Your AWS access key
Secret Access Key - Your AWS secret key
Region - AWS region (e.g., us-east-1)
Service - AWS service name (e.g., s3, execute-api)
Session token (optional) - The token that goes with temporary credentials (STS, SSO, assumed roles)

With a session token, hitspec sends it as X-Amz-Security-Token and includes that header in the signature:

### AWS request with temporary credentials
# @name awsTemporary
# @auth aws {{accessKey}}, {{secretKey}}, {{region}}, {{service}}, {{sessionToken}}

GET https://{{service}}.{{region}}.amazonaws.com/resource

>>>
expect status 200
<<<

If you leave the fifth parameter out and the access key equals $AWS_ACCESS_KEY_ID, hitspec uses $AWS_SESSION_TOKEN when it is set. The signature covers the exact bytes that are sent, including a >>>multipart body.

OAuth2 Client Credentials

Automatically fetches an access token using the OAuth2 Client Credentials grant before sending the request.

### Access with OAuth2 client credentials
# @name oauth2ClientRequest
# @auth oauth2 client_credentials {{tokenUrl}}, {{clientId}}, {{clientSecret}}, scope1,scope2

GET {{baseUrl}}/api/resource

>>>
expect status 200
<<<

Parameters in order:

Token URL - The OAuth2 token endpoint
Client ID - Your application’s client ID
Client Secret - Your application’s client secret
Scopes - Comma-separated list of scopes (optional)

OAuth2 Password Grant

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

### Access with OAuth2 password grant
# @name oauth2PasswordRequest
# @auth oauth2 password {{tokenUrl}}, {{clientId}}, {{clientSecret}}, {{username}}, {{password}}, scope1,scope2

GET {{baseUrl}}/api/resource

>>>
expect status 200
<<<

Parameters in order:

Token URL - The OAuth2 token endpoint
Client ID - Your application’s client ID
Client Secret - Your application’s client secret
Username - Resource owner’s username
Password - Resource owner’s password
Scopes - Comma-separated list of scopes (optional)

Using Auth with Captures

A common pattern is to capture a token from a login request and use it in subsequent requests:

### Login
# @name login

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

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

>>>
expect status 200
expect body.token exists
<<<

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

### Access protected resource
# @name protected
# @depends login
# @auth bearer {{login.token}}

GET {{baseUrl}}/me

>>>
expect status 200
<<<

Auth Syntax Reference

Method	Syntax
Bearer	`# @auth bearer <token>`
Basic	`# @auth basic <username>, <password>`
API Key (Header)	`# @auth apiKey <headerName>, <value>`
API Key (Query)	`# @auth apiKeyQuery <paramName>, <value>`
Digest	`# @auth digest <username>, <password>`
AWS Signature v4	`# @auth aws <accessKey>, <secretKey>, <region>, <service>[, <sessionToken>]`
OAuth2 Client Credentials	`# @auth oauth2 client_credentials <tokenUrl>, <clientId>, <clientSecret>, <scopes>`
OAuth2 Password	`# @auth oauth2 password <tokenUrl>, <clientId>, <clientSecret>, <username>, <password>, <scopes>`

All auth parameters support variable interpolation with {{variableName}} syntax, so you can store credentials in your environment configuration and keep them out of your test files.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Authentication for API tests (@auth)

Bearer Token

Basic Auth

API Key (Header)

API Key (Query String)

Digest Auth

AWS Signature v4

OAuth2 Client Credentials

OAuth2 Password Grant

Using Auth with Captures

Auth Syntax Reference