Overview

You can programmatically manage your Confluence shares via our Web API by generating an API Key.

Generating a New API Key

1. Navigate to the External Share for Confluence admin panel.

2. Select the API Keys tab.

3. Click Create New API Key.

Managing Your API Keys

The API Keys list shows the keys for your instance with the following filters and controls.

Status: Each key shows one of four states:

Status filter: Filter the list by All, Scheduled, Active, Expired, or Archived. The list defaults to Active, so archived keys are not shown until you select them.

Creator filter: Filter by the user who created a key. All creators are listed by display name, with an All option.

Sorting: Sort by API Key Name, Short Description, Created, Last updated, Valid from, Valid to, or Status. The list is ordered by Last updated, newest first, by default.

Paging: A page size selector (10 / 20 / 50 / 100) appears when there are more than 10 keys.

Archived keys offer the View action only. Keys that are not archived can be edited and archived.

Key Configuration & Permissions

Set up your API key and copy the key value before closing the dialog.

• Key Name - provide your own name for the API key, up to 40 characters long.

• Key Value - The unique string used for authentication. The full key is shown only once, immediately after creation, so copy it before closing the dialog. Afterwards the list shows a fingerprint (e.g. cfe4a91b8d27) instead of the key itself.

• Get Shares - determines whether get operation is allowed for the key.

• List Shares - determines whether list operation is allowed for the key.

• Create Shares - determines whether create operation is allowed for the key.

• Update Share - Toggle Allow/Disallow to permit modifying existing shares.

• Delete Shares - determines whether delete operation is allowed for the key.

• Not valid before - set the start date for key validity.

• Not valid after - set the invalidation date for the key.

• Allowed IPs - set IPs or IP range that can use the key.

• Description - description of the key. Maximum 4000 characters.

Tracking & Audit

Open a key to see how it has been configured and used. The details are split across three tabs.

Configuration: The current settings of the key, as described in Key Configuration & Permissions above.

Api Key Usage: Usage Count shows how many times the key has been used, and Last Usage Time shows when it was last used. Neither value can be edited.

View Configuration History: A record of every change made to the key, with one row per version:

Using the Web API with API key

With key generated, you can now make a call to Web API. First of, set Authorization and Content-Type headers in your REST client.

Authorization: 'Bearer { KEY_VALUE }'Content-Type: 'application/json'

With the headers set, you can perform the following operations: GET, LIST, CREATE, and DELETE.

GET OPERATION

This operation allows you to retrieve a single share based on share uuid. This operation does not accept any additional options and returns JSON with Share data.

Example Call:

GET https://confluence.external-share.com/webapi/share/{ SHARE_UUID }

LIST OPERATION

This operation allows you to retrieve a sorted list of shares based on options passed. You need to have an access to shared issues to be able to list shares. You can pass the following options as request parameters:

• sort - share field by which the list will be sorted. The default value is “id”. In general, you can sort by any Share’s field as long as it is in a snake_case instead of camelCase. For example, you can sort by Issue ID, by passing “issue_id” (instead of issueId as returned in the JSON).

• sortOrder - order in which list will be sorted. Pass “asc” for ascending list; “desc” for descending list. “asc” is default.

• limit - defines how many shares will be returned in a single call. Default is 100.

• offset - defines how many positions from the start of the list will be ommited. Combined with limit parameter, this parameter may be helpful in performing concurrent calls. The default value is 0, which means the very first share on the list will be returned.

• contents- returns all shares for content IDs range. Content IDs should be comma separated. Example: contents=234451,4847

• spaceKeys - returns all shares in the selected spaces. Space IDs should be comma separated. Example: spaceKeys=SPACE1, ANOTHERSPACE

NOTE: If you are an administrator, you may ommit passing contents and/or spaces - this will result in returning all shares from all spaces you have admin rights. However, if you are not an administrator, the call will not be accepted and FORBIDDEN http status will be returned.

Example Call:

GET https://confluence.external-share.com/webapi/share?sort=uuid&sortOrder=desc&contents=1123,412344

CREATE OPERATION

This operation allows you to create a new share. The operation requires passing request body with contentId as mandatory field.

You may also pass additional fields:

"selectedUsersConfig": {        "allowed": true,        "allowedNotification": false,         "list": [{"email": "expl@expl2.com"}, {"email": "expl@expl.com"}]    }

Example Call:

POST https://confluence.external-share.com/webapi/share{    "contentId": "2556174",    "contentType": "PAGE",    "spaceId": "213516917",    "description": "This is internal description - not visible on share",    "name": "Name of the link - External Share Link if left empty",    "showComments": true,    "allowAddComment": false,    "showAttachments": true,    "selectedUsersConfig": {        "allowed": true,        "allowedNotification": false,         "list": [{"email": "expl@expl2.com"}, {"email": "expl@expl.com"}]    }}

DELETE OPERATION

This operation allows you to delete a single share based on its share uuid. It does not accept any additional options. Upon successful execution, it returns no content (HTTP 204). If an error occurs, a JSON with the error message will be provided.

Example Call:

DELETE https://confluence.external-share.com/webapi/share/{SHARE_UUID}