Rate this page:

API proxy

Used to create a layer between your API and Bitbucket to provide the heavy lifting for authentication, parameter substitution, object hydration, and other services. You can read about how Bitbucket's API proxy works and how to use it in the Proxy module guide.

Sample descriptor JSON

You create the proxy connection when you map a URL pattern to a specific destination URL in your app descriptor. The simplest form of this is:

"modules": {
    "proxy": {
        "/proxy-example/{repository}": {
            "destination": "/proxy-example?name={repository.owner.display_name}", // required
            "methods": { ... }, // optional
            "conditions": { ... }, // optional
            "scopes": { ... } // optional

In this example, the context parameter {repository} needs to be captured using the UUID. However, for objects that belong to another object -- like how a repository belongs to a user or team -- the parent object needs to be resolved in order to resolve a child object. Read more about this in the subsection of the article about Object hydration, Capturing the parent object of the object you're capturing.

Path definitions

The path definition will be the URL that's transformed by Bitbucket and is served to clients.



DescriptionThe destination for a proxy path. This can be a fully qualified, absolute URL, or it can be just a path. In case of the latter, it is concatenated to the base URL. Destination URLs can contain Connect context parameters that will be substituted at runtime with request properties.


DescriptionThe HTTP methods GET, PUT, POST and DELETE can be defined inside the methods property in order to explicitly define which methods are can be forwarded. Within this method definition, destination, scopes or conditions can be defined as properties to override the properties at the top level for the path definition.
DescriptionThe scopes property can be used to define the scopes a request needs in order to be able to access the resource. For more details refer to the list of Rest API Scopes.
Type[Simple condition, Composition condition]
DescriptionAn array of conditions used to restrict access to the resource.

Declaring conflicting conditions or scopes

If nested scopes or conditions conflict, values declared by a child element will override values declared by parent elements. See the Restrict HTTP methods example in the API proxy module guide for an example of conflicting nested conditions.

Rate this page: