Provisioning
This section is not complete yet for end users. For developers, you can read the documentation for the API below:
Provisioning API for matrix-hookshot
Overview
This document describes how to integrate with matrix-hookshot
's provisioning API.
Requests made to the bridge must be against the API listener defined in the config under provisioning
, not
the appservice or webhook listeners.
Requests should always be authenticated with the secret given in the config, inside the Authorization
header.
Requests being made on behalf of users (most provisioning APIs) should include the userId as a query parameter.
GET /v1/health?userId=%40Half-Shot%3Ahalf-shot.uk
Authorization: Bearer secret
APIs are versioned independently so two endpoints on the latest version may not always have the same version.
APIs
GET /v1/health
Request the status of the provisioning API.
Response
HTTP 200
{}
Any other response should be considered a failed request (e.g. 404, 502 etc).
GET /v1/connectiontypes
Request the connection types enabled for this bridge.
Response
{
"JiraProject": {
"type": "JiraProject", // The name of the connection
"eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type for the connection
"service": "jira", // or github, webhook. A human-readable service name to make things look pretty
"botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently, this is the sender_localpart, but may change in the future.
}
}
GET /v1/{roomId}/connections
Request the connections for a given room. The {roomId}
parameter is the target Matrix room.
Response
[{
"type": "JiraProject", // The name of the connection
"eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
"id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
"service": "jira", // or github, webhook. A human-readable service name to make things look pretty
"botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently, this is the sender_localpart, but may change in the future.
"config": {
// ... connection specific details, can be configured.
}
}]
GET /v1/{roomId}/connections/{id}
Request details of a single connection. The {roomId}
parameter is the target Matrix room.
Response
{
"type": "JiraProject", // The name of the connection
"eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
"id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
"service": "jira", // or github, webhook. A human-readable service name to make things look pretty
"botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently, this is the sender_localpart, but may change in the future.
"config": {
// ... connection specific details, can be configured.
}
}
PUT /v1/{roomId}/connections/{type}
Create a new connection of a given type. The type refers to the eventType
(IConnection.CanonicalEventType
). The {roomId}
parameter is the target Matrix room.
The body of the request is the configuration for the connection, which will be the "ConnectionState" interface for each connection.
Request body
{
// ... connection specific details, can be configured.
}
Response
{
"type": "JiraProject", // The name of the connection
"eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
"id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
"service": "jira", // or github, webhook. A human-readable service name to make things look pretty
"botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently, this is the sender_localpart, but may change in the future.
"config": {
// ... connection specific details, can be configured.
}
}
PATCH /v1/{roomId}/connections/{id}
Update a connection's configuration. The id
refers to the id
returned in the GET response.
The body of the request is the configuration for the connection, which will be the "ConnectionState" interface for each connection.
Request body
{
// ... connection specific details, can be configured.
}
Response
{
"type": "JiraProject", // The name of the connection
"eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
"id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
"service": "jira", // or github, webhook. A human-readable service name to make things look pretty
"botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently, this is the sender_localpart, but may change in the future.
"config": {
// ... connection specific details, can be configured.
}
}
DELETE /v1/{roomId}/connections/{id}
Delete a connection. The id
refers to the id
returned in the GET response.
Response
{
"ok": true
}
Service specific APIs
Some services have specific APIs for additional functionality, like OAuth.
GitHub
GET /v1/github/oauth?userId={userId}
Request an OAuth url for the given user. Once the user has completed the steps in the OAuth process, the bridge will be granted access.
Response
[{
"user_url": "https://github.com/login/oauth/authorize?...",
"org_url": "https://github.com/apps/matrix-bridge/installations/new",
}]
GET /v1/github/account?userId={userId}
Request the status of the users account. This will return a loggedIn
value to determine if the
bridge has a GitHub identity stored for the user, and any organisations they have access to.
Response
{
"loggedIn": true,
"organisations":[{
"name": "half-shot",
"avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4"
}]
}
GET /v1/github/orgs/{orgName}/repositories?userId={userId}&page={page}&perPage={perPage}
Request a list of all repositories a user is a member of in the given org. The owner
and name
value of a repository can be given to create a new GitHub connection.
This request is paginated, and page
sets the page (defaults to 1
) while perPage
(defaults to 10
) sets the number of entries per page.
This request can be retried until the number of entries is less than the value of perPage
.
Response
{
"loggedIn": true,
"repositories":[{
"name": "matrix-hookshot",
"owner": "matrix-org",
"fullName": "matrix-org/matrix-hookshot",
"avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4",
"description": "A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. "
}]
}
GET /v1/github/repositories?userId={userId}&page={page}&perPage={perPage}
Request a list of all repositories a user is a member of (including those not belonging to an org). The owner
and name
value of a repository can be given to create a new GitHub connection.
If the user has only allowed a subset of repositories to be bridged, changeSelectionUrl
will be defined and can be used to expand the search query.
This request is paginated, and page
sets the page (defaults to 1
) while perPage
(defaults to 10
) sets the number of entries per page.
This request can be retried until the number of entries is less than the value of perPage
.
Response
{
"loggedIn": true,
"changeSelectionUrl": "https://github.com/settings/installations/12345",
"repositories":[{
"name": "matrix-hookshot",
"owner": "matrix-org",
"fullName": "matrix-org/matrix-hookshot",
"avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4",
"description": "A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. "
}]
}
JIRA
GET /v1/jira/oauth?userId={userId}
Request an OAuth url for the given user. Once the user has completed the steps in the OAuth process, the bridge will be granted access.
Response
{
"url": "https://auth.atlassian.com/authorize?..."
}
GET /v1/jira/account?userId={userId}
Request the status of the users account. This will return a loggedIn
value to determine if the
bridge has a JIRA identity stored for the user, and any instances they have access to. Note that if a
user does not have access to an instance, they can authenticate again to gain access to it (if they are able
to consent).
Response
{
"loggedIn": true,
"instances":[{
"name": "acme",
"url": "https://acme.atlassian.net"
}]
}
GET /v1/jira/instances/{instanceName}/projects?userId={userId}
Request a list of all projects a user can see in a given instance. The url
value of a project can be given to create
a new JIRA connection.
Response
[{
"key": "PLAY",
"name": "Jira Playground",
"url": "https://acme.atlassian.net/projects/PLAY"
}]