API: OAuth 2

TBD

Methods

Get the oauth application.

Retrieves the OAuth 2 provider application for the given identifier. The secret will not be part of the response, instead a confidential flag is indicating, whether there is a secret or not.

id
integer

required path

OAuth application id

Example:
1337

200

OK

OAuthApplicationReadModel
{
  "type": "object",
  "required": [
    "id",
    "_type",
    "name",
    "clientId",
    "confidential",
    "_link"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "_type": {
      "type": "string",
      "enum": [
        "OAuthApplication"
      ]
    },
    "name": {
      "type": "string",
      "description": "The name of the OAuth 2 application"
    },
    "clientId": {
      "type": "string",
      "description": "OAuth 2 client id"
    },
    "clientSecret": {
      "type": "string",
      "description": "OAuth 2 client secret. This is only returned when creating a new OAuth application."
    },
    "confidential": {
      "type": "boolean",
      "description": "true, if OAuth 2 credentials are confidential, false, if no secret is stored"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the OAuth 2 Application was created at"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the OAuth 2 Application was last updated"
    },
    "scopes": {
      "type": "array",
      "description": "An array of the scopes of the OAuth 2 Application",
      "items": {
        "type": "string"
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "owner",
        "redirectUri"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This OAuth application\n\n**Resource**: OAuthApplication"
            }
          ]
        },
        "owner": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user that created the OAuth application.\n\n**Resource**: User"
            }
          ]
        },
        "integration": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The resource that integrates this OAuth application into itself. Currently, only `Storage` resources are\nable to create and maintain own OAuth application.\n\n**Resource**: Storage"
            }
          ]
        },
        "redirectUri": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The redirect URI of the OAuth application\n\n**Resource**: N/A"
            }
          ]
        }
      }
    }
  },
  "example": {
    "id": 1337,
    "_type": "OauthClientCredentials",
    "name": "Vader's secure OAuth app",
    "clientId": "O5h6WObhMg1Z8IcLHRE3_LMh4jJYmmca2V6OTFSv8DA",
    "confidential": true,
    "createdAt": "2022-12-07T12:56:42.626Z",
    "updatedAt": "2022-12-07T12:56:42.626Z",
    "scopes": [
      "api_v3"
    ],
    "_links": {
      "self": {
        "href": "/api/v3/oauth_applications/1337"
      },
      "owner": {
        "href": "/api/v3/users/13",
        "title": "Darth Vader"
      },
      "integration": {
        "href": "/api/v3/storages/42",
        "title": "Death Star Cloud"
      },
      "redirectUri": {
        "href": "https://death-star.cloud.tools/index.php/apps/integration_openproject/oauth-redirect"
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: admin

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the application does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Get the oauth client credentials object.

Retrieves the OAuth 2 client credentials for the given identifier. The secret will not be part of the response, instead a confidential flag is indicating, whether there is a secret or not.

id
integer

required path

OAuth Client Credentials id

Example:
1337

200

OK

OAuthClientCredentialsReadModel
{
  "type": "object",
  "required": [
    "id",
    "_type",
    "clientId",
    "confidential",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "_type": {
      "type": "string",
      "enum": [
        "OAuthClientCredentials"
      ]
    },
    "clientId": {
      "type": "string",
      "description": "OAuth 2 client id"
    },
    "confidential": {
      "type": "boolean",
      "description": "true, if OAuth 2 credentials are confidential, false, if no secret is stored"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the OAuth client credentials were created at"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the OAuth client credentials were last updated"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "integration"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This OAuth Client Credentials object\n\n**Resource**: OAuthClientCredentials"
            }
          ]
        },
        "integration": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The resource that integrates this OAuth client credentials. Currently, only `Storage` resources are\nable to contain OAuth client credentials.\n\n**Resource**: Storage"
            }
          ]
        }
      }
    }
  },
  "example": {
    "id": 1337,
    "_type": "OAuthClientCredentials",
    "clientId": "O5h6WObhMg1Z8IcLHRE3_LMh4jJYmmca2V6OTFSv8DA",
    "confidential": true,
    "createdAt": "2022-12-07T12:56:42.836Z",
    "updatedAt": "2022-12-07T12:56:42.836Z",
    "_link": {
      "self": {
        "href": "/api/v3/oauth_client_credentials/1337"
      },
      "integration": {
        "href": "/api/v3/storages/42",
        "title": "Death Star Cloud"
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: admin

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the object does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}