Authentication
One @auth line says how a request proves who it is, and Stampdrill builds the header. It saves copying an Authorization header into every request, and it keeps the token itself out of the file: the line names a variable, the variable holds the value.
The usual shape is two requests. The first logs in and keeps the token, the second uses it.
# account.stamp
@base = https://dummyjson.com
### Log in
POST {{base}}/auth/login
Content-Type: application/json
{ "username": "emilys", "password": "{{secret("emilyspass")}}" }
> assert status == 200
> set token = body.accessToken
### My account
@needs logIn
@auth bearer {{token}}
GET {{base}}/auth/me
> assert status == 200
> assert body.firstName == "Emily"
That account is a demo one published by dummyjson.com, so the file runs as it stands. Four things are doing the work:
set token = body.accessToken | keeps a value from the response for every later request in the session |
@needs logIn | runs the login first when it has not already run, so the second request can be sent on its own |
@auth bearer {{token}} | sends Authorization: Bearer and the token |
secret(...) | keeps the password out of the printed request; see Secrets for where it should live |
stamp run account.stamp
→ POST https://dummyjson.com/auth/login account.stamp › logIn
200 OK 122 ms 930 bytes
✓ status == 200
→ GET https://dummyjson.com/auth/me account.stamp › myAccount
200 OK 105 ms 1 KB
✓ status == 200
✓ body.firstName == "Emily"
✓ 2 requests, 3 assertions
The word Bearer is added for you, and not added twice if the value already starts with it.
Most APIs need nothing more. What follows is the other schemes, and the rules for which one a request ends up with.
@auth bearer {{token}} | Authorization: Bearer … |
@auth jwt {{idToken}} | the same header; the app also reads the token's claims |
@auth basic {{username}} {{password}} | Authorization: Basic …, the pair encoded |
@auth apikey X-API-Key {{apiKey}} | that header, with that value |
@auth apikey api_key {{apiKey}} query | the key as a query parameter instead |
@auth none | no authentication, whatever the file says |
A key in the query string ends up in logs and in reports, so prefer the header when the API accepts one.
Where the line goes. An @auth line before the first request belongs to the whole file, and every request in it inherits it. A request writes its own to disagree, including @auth none for the one endpoint that is open. A header typed into a request beats both, which is the way to try a token by hand without touching anything else.
@auth bearer {{token}}
### Health
@auth none
GET https://httpbingo.org/status/200
> assert status == 200
OAuth 2. When there is a token endpoint rather than a login, name it and the runner fetches a token before sending, then reuses it until it expires. The token lives in the session rather than in a file, and it is masked like any secret.
### List orders
@auth oauth2 client_credentials token_url={{idp}}/token client_id=orders-service client_secret={{clientSecret}} scope="orders:read"
GET {{base}}/orders
> assert status == 200
The settings are token_url, client_id, client_secret, scope, audience, username and password. The client credentials grant needs the first two; the password grant also needs a user name and a password:
@auth oauth2 password token_url={{idp}}/token client_id=orders-service username={{username}} password={{password}}
These two snippets are fragments: they need an idp and a clientSecret of your own, so they will not run against anything until you point them at your identity provider.
In the app
- Pick the request and open its Auth tab.
- Choose from Type: Same as File, No Auth, Bearer Token, JWT Bearer, Basic Auth, API Key or OAuth 2. The fields below change with the choice, and the line under the picker says the value is stored as an
@authline in the request and that a header typed under Headers wins over it. - Fill in the fields the scheme needs: Token for a bearer or a JWT, Username and Password for basic, Name, Value and a Send in choice of header or query for an API key, Grant, Token URL, Client ID and Client Secret for OAuth 2. Each field is written into the file when you leave it.
- On Same as File, read the File uses row: it names the scheme the file set, so an inherited one is never a guess.
- On JWT Bearer, read Claims under the field. Every claim is listed, and a Status row says Expired or Valid until a date.
The tab writes the @auth line and nothing else, so the file stays the record of what the request does. What it adds is the reading of the token: the claims decoded in place, with the expiry called out, which answers the usual question about a 401 faster than reading the response does.

Next: Secrets for where a password or a client secret is written, Scripts and assertions for what else a response can leave behind, and Variables and dimensions for a different account per run.