Manage policy packages using the API

In addition to the Policy editor in the Authorization Hub user interface, you can manage ALFA policies programmatically using the Policies API. This is useful when integrating policy management into CI/CD pipelines or external tooling.

The API requires an access token and the Project editor role (or higher) in the project. Read the API overview to get started, and the Policies endpoint reference for the full list of endpoints and fields.

Key parameters

When handling policy packages through the API, use the following values:

Parameter	Value	Notes
X-Project-Id header	Your project ID	You can retrieve the project ID through: - the GET /api/projects endpoint - the Authorization Hub interface after opening the project and extracting it from the URL. For example, in https://sample.hub.domain/projects/e00f12c8-8f3a-40ac-81a7-5a762abc7288/dashboard, the project ID is e00f12c8-8f3a-40ac-81a7-5a762abc7288.
packageName	policypackage	The Policy editor uses a single policy package per project, named policypackage. Use this name to work with the same policies in the editor and through the API.

Update policies

A typical update from a pipeline follows these steps:

1. Check that the package exists. A request to GET /api/policy-package/policypackage returns 404 with the POLICY_PACKAGE_NOT_FOUND error code if the project has no policies yet. In that case, create the package with POST /api/policy-package.

2. Send your changes. Use PATCH /api/policy-package/policypackage to add, update, rename, or remove policies:

   curl -X PATCH "https://<authorization-hub-url>/api/policy-package/policypackage" \
     -H "Authorization: Bearer <access_token>" \
     -H "X-Project-Id: <project-id>" \
     -H "Content-Type: application/json" \
     -d '{
       "policies": [
         { "name": "access.alfa", "action": "UPDATE", "contents": "namespace access { /* ... */ }" },
         { "name": "obsolete.alfa", "action": "REMOVE" }
       ]
     }'

3. Save the changes to the project. If My workspace is enabled, the request returns 202 and your changes are staged in your workspace. Promote the workspace to apply them. Read My workspace and the API.

4. Compose a domain. Domains only use changes that have been saved to the project. Read Domains.

What an update changes

When you update a policy package with the PATCH request, you can modify the policies and the package metadata. The request affects only what you include:

• Unspecified policies remain intact. Only the policies you list in the request are affected.
• To delete a policy, list it with the action REMOVE.
• To rename a policy, use the action UPDATE with the new name in newName.
• Metadata that you send is merged into the existing package metadata when your workspace is promoted. Keys that you do not send are kept, and entries for policies that your changes do not touch are preserved.

Each update creates a new version of the package.

Attribute requirements

There is an important difference in how attributes are handled depending on whether you use the UI or the API.

UI:

• The attribute-dictionary.alfa file is auto-generated from the Dictionary and stored automatically with every save.
• A jsonAttributes entry in the package metadata (a JSON representation of the attributes actively referenced in the policy) is also generated and stored automatically.

API:

• You do not need to provide an attribute-dictionary.alfa file.
• However, the ALFA definitions of all attributes used in the policy must be present within one or more of the files included in the policy package. If attribute definitions are missing, the domain compose step will fail.
• When you compose a domain through the API, you send the attribute definitions in the compose request. Read Domains.

note

Attributes defined only in ALFA files (and not added to the Dictionary) cannot be used in attribute connector configurations as provided or key attributes, and no caching configuration can be applied to them.

info

Authorization Hub does not compile ALFA when you save it through the API. Syntax errors and unresolved references are reported when you compose a domain.

Export and import

You can export the published policies as a single JSON file, and import such a file into the same or another project. Read Import and export for the file format and the behavior of an import, and the Policies endpoint reference for the requests.

API reference

The full schema and endpoint definitions for the Policies API are available in the Hub service Swagger UI, in the Policies definition:

http(s)://<authorization-hub-url>/api/hub-service/swagger-ui/index.html

Read the Policies endpoint reference for descriptions of the endpoints, fields, and errors.