Last updated Mar 27, 2024

REST and os_authType

This functionality is part of the Atlassian REST plugin 2.1.0 and Seraph 2.2 releases. See the REST API Plugin version matrix for availability.

One common problem with REST API access to Atlassian applications is dealing with authentication.

To authenticate some remote clients use cookies, just like a web browser does. That is, they acquire a login and a cookie and then submit the cookie with each request. The downside to this approach is that cookies eventually expire. When this happens you are treated as an anonymous user.

As a user, you've probably noticed this when, once in a while, you go to an Atlassian app and have to log in again. As a human, this situation is pretty easy to detect and fix. For something that is programmatically interacting with an application, it is much harder to detect! Imagine that you submit a query to JIRA and, instead of getting back 200 results, you get back only the 5 issues that anonymous users can see. Nothing obviously failed but you don't get the results you want.

To avoid this, Atlassian applications treat cookie expiration differently under the /rest URLs. If you submit an expired cookie to a REST resource under the /rest URL, you receive a 401 error response instead of silently being treated as an anonymous user. Thus, the REST application can resubmit credentials in this case.

Note that this behaviour does not apply, by default, to other parts of the system. This only affects /rest URLs.

However, some applications may want to replicate this behaviour across the entirely of the system. For instance, if you are performing some kind of screen-scraping you might like to have this happen everywhere.

You can trigger this behaviour by adding the os_authType query parameter in your URL. os_authType supports the following parameters and behaviour:

os_authType

behaviour

basic

The server will return a 401 error response and perform an HTTP Basic Authentication challenge if no username and password is specified

cookie

The server will return a 401 error response if a valid cookie is not provided in the request

any

If a username and password are not specified and there is not valid cookie, the server will return a 401 error response

Rate this page: