Guide

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.accessTokenkeeps a value from the response for every later request in the session
@needs logInruns 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}} querythe key as a query parameter instead
@auth noneno 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

  1. Pick the request and open its Auth tab.
  2. 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 @auth line in the request and that a header typed under Headers wins over it.
  3. 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.
  4. On Same as File, read the File uses row: it names the scheme the file set, so an inherited one is never a guess.
  5. 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.

The Auth tab, with Type set to JWT Bearer and the line it writes into the file named under it
The Auth tab, with Type set to JWT Bearer and the line it writes into the file named under it

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.

Updated

Back: Secrets Next: Scripts and assertions