API overview

Everything you can do in the Authorization Hub interface is also available through its REST API. Use the API to integrate Authorization Hub with CI/CD pipelines, scripts, and external tooling. For example, to keep attributes and policies in source control, or to compose a domain after a policy change.

All requests are sent to your Authorization Hub URL and are served through a single gateway, so you only need one base URL:

https://<authorization-hub-url>/api/...

Available APIs

Area	Base path	Reference
Projects	/api/projects	Projects and users
Users and clients	/api/principal	Projects and users
Attributes, namespaces, and cache profiles	/api/dictionary/attributes, /api/namespaces, /api/cache-profiles	Dictionary
Attribute connectors	/api/attribute-connectors	Attribute connectors
Policies	/api/policy-package	Policies
Domains	/api/domains, /api/adm	Domains
Policy insights	/api/insights	Policy insights
Activity feed	/api/collaboration/activity-feed	Activity feed
My workspace	/api/drafts	My workspace and the API
License and health	/api/license/status, /actuator/health	Platform endpoints

Interactive API documentation

Authorization Hub publishes an OpenAPI definition for each service, with a Swagger UI to browse it:

Service	Swagger UI	OpenAPI definition
Hub service (projects, dictionary, attribute connectors, policies, domains, drafts, policy insights, activity feed)	https://<authorization-hub-url>/api/hub-service/swagger-ui/index.html	https://<authorization-hub-url>/api/hub-service/api-docs
Domain manager service (reading domains, history)	https://<authorization-hub-url>/api/adm-service/swagger-ui/index.html	https://<authorization-hub-url>/api/adm-service/api-docs

Keep the following in mind when using the documentation pages:

• Sign in first. The documentation pages are only available to signed-in users. Open Authorization Hub in the same browser before you open the Swagger UI.
• Try it out is disabled in the Hub service Swagger UI. Copy the request into your HTTP client of choice instead.
• Select a definition. The Hub service Swagger UI groups its endpoints (for example, Dictionary, Attribute-Connectors, Policies) in the definition dropdown.
• Users and clients endpoints are not listed. The /api/principal endpoints are not part of the Swagger UI. They are documented in Projects and users.
• Domain compose is not listed in the domain manager definition. Compose domains through the Hub service endpoint described in Domains.

Make your first request

1. Create a client and obtain an access token for your pipeline or script.

2. Add the client to the project it needs to work with, using a project role that grants the access you need. Read Permissions for details.

3. Find the project ID. Either list the projects the client can see:

   curl -X GET "https://<authorization-hub-url>/api/projects" \
     -H "Authorization: Bearer <access_token>"

   or open the project in the interface and copy the ID 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.

4. Call an endpoint of that project, sending the project ID in the X-Project-Id header:

   curl -X GET "https://<authorization-hub-url>/api/dictionary/attributes" \
     -H "Authorization: Bearer <access_token>" \
     -H "X-Project-Id: <project-id>"

Request headers

Header	Used for	Notes
Authorization	All requests	Bearer <access_token>. Read Client management.
X-Project-Id	All project-scoped requests	The project ID. See the note below.
Content-Type	Requests with a body	application/json in general. Attribute and attribute connector updates (PATCH) require application/merge-patch+json. Imports use multipart/form-data.
X-Draft-Id	Writes that are staged in My workspace	Optional. Targets an existing workspace.
User-Email	GET /api/principal/users/email only	The email address to look up.

warning

Always send X-Project-Id on project-scoped requests. If the header is missing, the request is rejected with 403 and the MISSING_PROJECT_ID error code on most endpoints. Do not rely on a default: a request without a project is never applied to one of your projects.

The project endpoints (/api/projects) and the users and clients endpoints (/api/principal) do not use the header.

Conventions

• Format: Requests and responses are JSON, unless stated otherwise. Dates and times use the ISO-8601 format. Resource IDs are UUIDs.
• Fully qualified names: Attributes and attribute connectors are addressed by their fully qualified name (FQN), which is <namespace>.<name>. The name is whatever follows the last dot, so a namespace can itself contain dots. A policy is addressed as <package>/<policy file name>.
• Versioning model: Attributes, attribute connectors, cache profiles, and policy insights templates are never edited in place. An effective update creates a new version and retires the previous one, and a delete retires the item so its name can be reused. Reading by name returns the active version, and reading by ID can return older versions.
• Pagination: Most list endpoints return all items in a plain array. Only the activity feed and the policy insights reports and templates lists are paginated.
• Unknown fields: Unknown fields in ordinary request bodies are ignored. Import files and domain manager requests are stricter and reject unknown fields.
• Errors: Read Errors for the error response formats and status codes.

Limits and availability

• License: If your license has expired, API requests are rejected with 403 and the LICENSE_EXPIRED error code. The exception is GET /api/license/status, which keeps working so that you can check the license status. Read License and Platform endpoints for details.
• Timeouts: Requests that depend on the domain manager, such as composing or rolling back a domain, time out after five minutes by default.
• Rate limiting: Authorization Hub does not apply built-in rate limiting. Rate limits imposed by your own infrastructure, such as a load balancer or web application firewall, still apply.
• Calling from a browser: Browser applications served from another origin can call the API only if their origin is allowed in your deployment's cross-origin configuration. Contact your administrator.