Login & token

When you test a protected API you do not have to add the token to every step by hand. In Login & token you define the login request once; Spitfire signs in for each VU, takes the token from the response and adds it to every request of the test. It signs in again by itself when the token expires or the server answers 401.

#Define the login request

1. On the Tests page In Spitfire: /tests open the test and click Edit.
2. In the Login & token card at the top of the Scenarios & steps tab, pick Login request.
3. Type the method and the address, e.g. POST and:

{{base}}/auth/login

4. On the Body tab pick JSON and paste the credentials:

{"username": "{{users.email}}", "password": "{{users.password}}"}

5. Leave Source on JSON body; type the token's path in JSONPath (see the examples below):

data.access_token

6. With Variable left empty the token is {{token}}. Sent in defaults to the Authorization: Bearer {{token}} header.
7. Under Refresh leave On 401: sign in again + retry once ticked.
8. Click Try the login.

How you know it worked: a green Signed in (200), token: appears next to the button with the token masked (e.g. eyJh…x9Qk (212)). If the path is wrong, a red box lists the paths the response has (e.g. $.token not found; the response has: data.access_token, data.expires_in); copy the right one from the list.

#Finding the token with JSONPath

You do not need the leading $.; data.token and $.data.token are the same.

If the response is XML, pick XML body as Source and write an XPath:

//LoginResult/Token

If the token comes in a response header, pick Response header and type its name (e.g. X-Auth-Token). If the server opens a session with a cookie, pick Cookie: each VU's cookie jar sends the cookie itself and no header is added.

#How the token is sent

Fill Sent in and Format the way your API expects it:

The header shows as a read-only row in the Shared headers list (From Login & token). A step that writes a header of the same name itself keeps its own.

#Refresh

• Sign in again every: each VU renews its token when this much time has passed (e.g. 15 min; at least 1 s).
• Lifetime (seconds) path: if the response gives a lifetime such as expires_in, type its path (data.expires_in); the token is renewed 30 s before it runs out.
• On 401 / 403: when a request answers that, the VU signs in again and sends the same request once more. If the second try answers 401 too, the step fails; there is no loop. A step with a check that expects 401 (an unauthorised access test, say) is not sent again.
• Refresh token path: the refresh token in the response goes into {{token_refresh}}; you can use it in the login request's body.

When the login fails (an error status, or no token in the response) the VU's iteration ends and the VU waits a second before it tries again in its next iteration, so a broken login is not hammered under load.

#Entering the token by hand

If you get the token elsewhere (a developer portal, say), pick I'll enter the token myself:

1. Paste the token into Token.
2. Set Sent in, Name and Format as in the table above.
3. Save the test.

How you know it worked: Try it at the top of the page gets 200 from the steps; the token row shows in the Shared headers list.

#Public steps

For steps that work without signing in, such as the home page, a health check or a sign-up:

1. Open the step and go to the More tab.
2. Tick Public · no login needed.

This step gets no token header, does not wait for the login, and a 401 on it does not sign in again (it is an ordinary failure). The login runs just before the VU's first step that is not public; when every step of the test is public, the login never runs. A ticked step shows a Public badge in its header.

#When importing

• OpenAPI: the document's securitySchemes are read. If you pick a login operation or an OAuth2 flow, the test comes with a Login & token block (for OAuth2 the lifetime path expires_in is set); if you give a token or an API key by hand, it comes in I'll enter the token myself mode. Operations with security: [], and operations without security when the document has no global security, become public steps.
• Postman: a collection-level bearer or API key auth moves into the block. Pre-request scripts that sign in or set a token are not run; the import screen shows a note about them, define the login request in the editor.
• HAR and Recorder: the recorded login comes in as a step. The editor notices a step that extracts a token used in other steps' headers and offers Use this step as the login: one click makes it the login request and removes the hand-written token headers from the steps.

#Try it on the demo target

The demo target that comes with install.sh --demo has a login whose token runs out, so you can watch the refresh happen:

1. Login request: POST and the demo target's address with /login?ttl=120, e.g.:

http://testtarget:8090/login?ttl=120

2. Body (JSON):

{"user": "ada", "password": "secret"}

3. JSONPath token, Lifetime (seconds) path expires_in.
4. Add a step GET http://testtarget:8090/items and run the test for 5 minutes.

How you know it worked: the Login & token card on the run page counts more than one login per VU. The token lives 120 s; /items answers 401 {"error": "token expired"} once it has run out. Clear the lifetime path to see the 401, the new login and the retried request instead.

#Good to know

• The token is added to HTTP, GraphQL, WebSocket and SSE steps. Browser steps get no token; the page opens its own session.
• The login uses the data row of the iteration it runs in ({{users.email}}); each VU signs in as its own user.
• Tests that run on an external engine (JMeter, Gatling, Locust, k6) do not have this section.