Jump to >

API Token Policies

New in version 2.5.

API tokens are used in Review Board 2.5+ to provide a safe form of authentication for clients without exposing any user passwords. It also offers a policy-based form of access control, limiting the capabilities of clients.

Token policies can globally limit HTTP methods, allow or block HTTP methods per-resource, or even allow or block them for specific resource item IDs. Policies are written in JSON format.

Despite the flexibility, it’s easy to write custom policies.

Policy Sections

All sections of a policy live in a top-level resources key:

{
    "resources": {
        ...
    }
}

All policy sections will go under resources.

Each section of a token policy should specify allow and/or block lists. These lists contain the list of all HTTP methods that are either allowed or blocked ("POST", "GET", "PUT", etc.). A special value of "*" in the list matches all HTTP methods, which is useful for allowing all methods by default and blocking just a few, or vice-versa.

Any part of the API that is denied by a policy will return a 101 - Permission Denied error.

Global Policy Section

Within resources, you can add a global policy section, "*", which sets the default allowed or blocked HTTP methods for all resources:

{
    "resources": {
        "*": {
            "allow": [<list of methods, or "*">],
            "block": [<list of methods, or "*">]
        }
    }
}

For example, to only allow read-only access to the API:

{
    "resources": {
        "*": {
            "allow": ["GET", "HEAD", "OPTIONS"],
            "block": ["*"]
        }
    }
}

Global policies apply to any and all resources, unless overridden by a more specific policy.

Resource Policy Sections

To allow or block access to a specific resource, add a section with the resources API policy identifier (found on any resource page in the documentation).

This may contain one or more sub-sections: "*", for rules applying to all items in that resource, or "<id>", where the ID matches the ID of the specific item in the resource that you want to limit access to.

The resource-global policy will apply to both lists and items.

The ID-specific policies are optional. In most cases, the resource-global policy is all that’s needed.

{
    "resources": {
        "*": {
            "allow": [<list of methods, or "*">],
            "block": [<list of methods, or "*">]
        },
        "<id>": {
            "allow": [<list of methods, or "*">],
            "block": [<list of methods, or "*">]
        },
        ...
    }
}

For example, to block all access to all repositories with the exception of allowing read access to repository ID 3:

{
    "resources": {
        "repository": {
            "*": {
                "block": ["*"]
            },
            "3": {
                "allow": ["GET", "HEAD", "OPTIONS"]
            }
        }
    }
}

Policy Tips

  • To allow read access, you’ll generally want to allow GET, HEAD, and OPTIONS in the allow list. GET isn’t always sufficient.
  • Clients are expected to follow links to get to a resource. Because of this, if you’re specifically allowing access to only certain resources, you will also generally need to allow access to their parent resources.
  • You probably want to allow Root List Resource and Server Info Resource, if you’re globally blocking GET on all resource.