mirror of
https://github.com/opf/openproject.git
synced 2026-06-14 03:30:14 +00:00
Jan Sandbrink
2a0aac1fa9
The main purpose is to make a deduplicating identifier available for interaction with integrations. We want to start using it for the integration with XWiki, but the underlying problem occurs regularly in integrations: It's possible for an OP instance to integrate with more than one XWiki instance. Vice versa it's also possible for one XWiki to integrate with multiple OPs. When this happens, API calls like "show me wiki pages that point to work package 123" become ambiguous, because WP 123 might exist on multiple OpenProject instances. Thus it makes sense to have a global identifier for the OpenProject instance. Different identifiers look good and unique at first, but they are not working well in detail: * Base URL (e.g. https://openproject.example.com): Some instances are available via more than one URL, e.g. inside cluster vs. outside cluster. * OAuth client ID: Usually not known to other party, and not guaranteed to be unique, because multiple authentication providers could be involved Hence we decided to use a uniquely generated ID and expose it in a way that doesn't require additional configuration by the users, but can be automatically discovered during integration setup.
73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
---
|
|
sidebar_navigation:
|
|
title: API documentation
|
|
priority: 910
|
|
---
|
|
|
|
# OpenProject API
|
|
|
|
OpenProject offers different APIs:
|
|
|
|
* API v3 (OpenProject's general purpose HATEOAS API)
|
|
* SCIM (System for Cross-domain Identity Management)
|
|
* MCP (Model Context Protocol)
|
|
* BCF API v2.1 api targeted towards BIM use cases
|
|
* .well-known endpoints
|
|
|
|
Please note that we intend to keep this specification as accurate and stable as possible, however work on APIs is still ongoing
|
|
and not all resources and actions in OpenProject are yet accessible through the APIs.
|
|
|
|
This document will be subject to changes as we add more endpoints and functionality. The development version of this document
|
|
may have breaking changes while we work on new endpoints for the application.
|
|
|
|
## API v3
|
|
|
|
The API v3 is a general purpose API supporting multiple use cases.
|
|
|
|
While by no means complete, a whole lot of different scenarios can be automatized which otherwise would have to be carried out by hand via the UI.
|
|
Examples for this include managing work packages, projects and users.
|
|
|
|
We strive to maintain backward compatibility with this API in our stable OpenProject releases whenever possible.
|
|
|
|
➔ [Go to OpenProject API](./introduction/)
|
|
|
|
### OpenAPI specification
|
|
|
|
Download the API specification in OpenAPI format as [json](https://www.openproject.org/docs/api/v3/spec.json) or [yml](https://www.openproject.org/docs/api/v3/spec.yml).
|
|
|
|
## SCIM
|
|
|
|
OpenProject allows to manage users and groups using System for Cross-domain Identity Management. This is a standardized API (see [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643) and [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644)) that might thus be supported by existing identity providers.
|
|
|
|
➔ [Read more on configuration instructions](../system-admin-guide/authentication/scim/)
|
|
|
|
## MCP
|
|
|
|
A growing number of tools and resources is offered through the Model Context Protocol API of OpenProject. This API is primarily targeted at AI agents and similar tools, as it supports auto-discovery of supported operations.
|
|
|
|
➔ [Read more on configuration instructions](../system-admin-guide/integrations/mcp-server/)
|
|
|
|
## BCF v2.1
|
|
|
|
This API supports BCF management in the context of BIM projects.
|
|
|
|
While this API supports way less use cases than the more generic *API v3* it is compatible with the generic specification of a BCF API as [defined by the standard](https://github.com/buildingSMART/BCF-API/blob/release_2_1/README.md). Clients implementing the specification can manage topics and viewpoints.
|
|
|
|
➔ [Go to BCF API](./bcf-rest-api/)
|
|
|
|
## .well-known endpoints
|
|
|
|
Each OpenProject installation exposes some endpoints under the `/.well-known/` path:
|
|
|
|
* `/.well-known/oauth-authorization-server`: [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414): OAuth 2.0 Authorization Server Metadata
|
|
* `/.well-known/oauth-protected-resource`: [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728): OAuth 2.0 Protected Resource Metadata
|
|
* `/.well-known/openproject-metadata`: Exposing non-confidential metadata about the OpenProject installation
|
|
|
|
### OpenProject Metadata
|
|
|
|
The `/.well-known/openproject-metadata` endpoint exposes some non-confidential metadata about the OpenProject instance in JSON format. This endpoint is accessible without authentication.
|
|
|
|
The following keys are exposed:
|
|
|
|
* `installation_uuid`: A unique identifier that's different per installation of OpenProject
|