Header/ Value Access Rules
Basics
With HTTP Header/ Value Access Rules you can define whether a request using an API Token for authentication should be allowed or denied based on the presence of an HTTP request header and optionally a value it has.
Example
The following curl command sends both the basic authentication header containing an API token and a header called REQ-ORIGIN with a value of 637623AhFGX.
- curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
- --header 'Authorization: Basic YWRtaW46dnRNZU5IbkpiZE5sWWgxcFU0NzZORE0zWHBEalltREtxVWo4amU=' \
- --header 'REQ-ORIGIN: 637623AhFGX'
Imagine having created a token with a rule that only allows authentication if that header and value are present. That rule could also allow (or deny) requests if the value matches a regular expression.
An HTTP header name should not contain underscores, because these are mostly filtered by reverse proxies or similar components.
Also, the use of the X- prefix for custom headers is not officially recommended anymore.
Rule Types
Allow Rules
Rules that define whether the authentication request will be allowed or not.
if a rule doesn't carry a value, the presence of the header is enough to allow the request
if there is more than one rule assigned to the token, at least one of them needs to match during authentication in order to allow it
header name checks are not case sensitive, so it doesn't matter if you setup rules with lower, mixed or uppercase header names
Example
A rule (1) that expects the value for the header REQ-ORIGIN to be a 3-digit number followed by the string XFEZ and a one-digit number again.
The rule tester (2) allows you to see which rule matches your test input. The request would be allowed then, provided that there are no deny rules that match.

Deny Rules
Rules that define whether the authentication request will be denied or not.
if a rule doesn't carry a value, the presence of the header is enough to deny the request
a match will deny the request, even if it would be allowed by allow-rules
header name checks are not case sensitive, so it doesn't matter if you setup rules with lower, mixed or uppercase header names
Example
Very similar to the allow-rule example, this rule expects the value for the header REQ-ORIGIN to be a 3-digit number followed by the string XFEZ and a one-digit number again.
The rule tester allows you to see which rule matches your test input. The request would be denied then, even if other allow rules would match.
Review Rules
If you need to see which rules have been assigned to your tokens, you can use the details button in the actions column in your token table.
The same is also available in the Token Manager view if you have permission to create tokens on behalf of other users.


In the above example, a header with the name REQ-ORIGIN and value 1 is required to allow the authentication request.
Caveats
Headers With Multiple Values
You are expected to send a header in your request only once, with a single value.
Below are two examples in Curl, the first one is containing the same header with different values.
Wrong
- curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
- --header 'REQ-ORIGIN: someValue' \
- --header 'REQ-ORIGIN: anotherValue' \
- --header 'Authorization: Bearer someApiTokenWithHeaderValueAccessRulesHere'
Right
- curl --location --request GET 'https://jira.company.com/rest/api/2/myself' \
- --header 'REQ-ORIGIN: anotherValue' \
- --header 'Authorization: Bearer someApiTokenWithHeaderValueAccessRulesHere'
Admins can see a warning about this in the log files, which might be helpful for troubleshooting.
- 2022-07-25 12:22:45,063+0000 http-nio-8080-exec-16 WARN anonymous 742x490x1 - 11.26.52.129,104.110.0.12 /rest/api/2/myself [d.r.a.platform.auth.ApiTokenAuthSharedBase] Found HTTP header 'req-origin' with multiple values that is referenced in header/ value access rules. Please only send each header once to avoid errors during rule evaluation.