Cookies
ApiWorkbench keeps the cookies servers set and sends them back on later requests, the way a browser does. You can inspect and change them at any time.
What a cookie is
A cookie is a small named value that a server asks the client to remember. The server sends it in a Set-Cookie response header. The client sends it back in the Cookie header of later requests to the same site. Sign-in sessions are the most common use: you log in once, and the session cookie proves who you are afterwards.
The place where the app keeps cookies is called the cookie jar.
How the cookie jar works
- Every response can add cookies, including each hop of a redirect.
- A request gets the cookies whose domain, path and
Secureflag match its URL. - A cookie is dropped when it expires, or when a server deletes it.
- Session cookies, which have no expiry date, are kept until you delete them, even after a restart.
- A
Cookieheader you add to a request yourself is still sent, in front of the cookies from the jar.
The jar is on by default. You do nothing to use it: log in with one request, and the next request to the same site is sent with the session cookie.
See the cookies of a response
After you send a request, open the Cookies tab of the response.
| Section | What it shows |
|---|---|
| Set by this response | The Set-Cookie headers of this response, taken apart into name, value and attributes. |
| Cookies in the jar for this URL | What the jar would send with the next request to this address. |
A line the jar could not accept is marked with the reason, for example "Ignored by the jar: Domain "…" does not match the host …". Select Manage to open the cookie manager.
Open the cookie manager
Select Cookies on the icon rail. On a phone, open the menu at the top right and choose Cookies…. Manage cookies… in Settings opens the same window.
The manager lists the domains that have cookies, each with a count. Select a domain to see its cookies. Search cookies narrows the list to domains whose name, or one of whose cookie names, contains your text.
Each cookie shows its name, its value and its attributes:
| Attribute | Meaning |
|---|---|
| Host or Domain | Host: sent only to this exact host. Domain: sent to this domain and all its subdomains, because the server set a Domain attribute. |
| Path | The cookie is only sent to URLs under this path. /api also covers /api/users. |
| Session, Expires or Expired | When the cookie is dropped. Session means no expiry date. |
| Max-Age | Seconds the cookie lives, counted from when it arrived. It wins over Expires. |
| Secure | Only sent over https. Requests to localhost and 127.0.0.1 count as secure, as in browsers. |
| HttpOnly | Browsers hide it from page scripts. ApiWorkbench still shows and sends it. |
| SameSite | Tells browsers when to send the cookie on cross-site requests. ApiWorkbench shows it but always sends the cookie. |
Add a cookie
In the cookie manager, select Add cookie.
In Domain, type the host the cookie belongs to, for example
api.example.com.In Set-Cookie line, type the cookie as a server would send it:
name=value, then optional attributes separated by semicolons.textsession=abc123; Path=/; Secure; Max-Age=3600Select Save.
Add Domain=example.com to the line to share the cookie with subdomains too.
Edit or delete cookies
- Edit one cookie: select the pencil on the cookie, change the line and select Save.
- Delete one cookie: select the delete icon on the cookie.
- Delete a domain's cookies: select the domain, then Clear domain.
- Delete everything: select Clear all.
Clear domain and Clear all ask you to confirm.
WARNING
Clear all removes every cookie from every domain. You are signed out of every site that used them, and the cookies cannot be brought back.
Turn cookies off
| Where | Setting | Effect |
|---|---|---|
| Settings, under Requests | Cookie jar | Off: no request sends stored cookies or keeps new ones. |
| A request's Settings tab | Use the cookie jar | Off: this request sends no stored cookies and keeps none from its response. |
Turning the jar off does not delete the cookies already in it.
Limits and storage
- The jar keeps up to 180 cookies per domain and 3,000 in total. When a limit is reached, the oldest cookies go first.
- A cookie whose
Domainis a public suffix, such as.com, is refused, as in browsers. - Cookies are stored unencrypted in
cookies.jsonin the app's data folder. See Where your data lives.
Scripts can read and write cookies with pm.cookies. See the script reference.