1 General information
2 How does it work
- 2.1 CURL Example
- 2.2 Postman Example
3 Specify limits for tokens
4 Secure mode
- 4.1 How to turn on Secure mode
5 REST API
- 5.1 Get all Tokens
- 5.2 Create Token
- 5.3 Delete Token
- 5.4 Disable/Enable "Usage Details" data collection
- 5.5 Disable/Enable adding token calls to the audit log
6 Changes

General information

A primary use case for API tokens is to allow scripts to access REST APIs for Confluence applications using HTTP basic authentication.

If you define a token for a user, only that user can use it. If you do not specify a user, any user will be able to use this token.

If an external system is compromised, you can revoke the token instead of changing the password and consequently changing it in all scripts and integrations.

For security reasons we recommend generating token for specific user.

Editing the token after creation is not possible, create a new token if necessary.

You should treat API tokens as securely as any other password.

Supported endpoints

CONFLUENCE_URL/rest/*

or if you turn on option Restrict tokens only for Extender endpoints in configuration

CONFLUENCE_URL/rest/extender/*

You can generate the code snippet (JavaScript/curl) and authentication data for calls by clicking icon

If you want to check who used the token and when, all calls are added to the audit log

How does it work

Depending on the details of the HTTP library you use, simply replace your password with the token. For example, when using curl, you could do something like this:

curl -v https://my-confluence.com --user USER:TOKEN

Note that:

USER here is the email address or user name.
TOKEN here is token generated in REST API Tokens page

CURL Example

GET Example

curl -s -u admin:token1234567890 CONFLUENCE_URL/rest/extender/1.0/user/getUserDetails/admin

curl -s -u ansible@confluence.pl:token0987654321 CONFLUENCE_URL/rest/extender/1.0/user/getUserDetails/admin

Postman Example

Note that :

Basic Auth use this type in Authorization type
Username here is the email address or user name.
Passwordhere is token generated in REST API Tokens page

Specify limits for tokens

You can restrict the token to specific specific methods (GET, POST, PUT, DELETE, etc.), URL's, URL parameters, and JSON data in the body.

Token restrictions for URLs, URL parameters, and JSON data in the body handling definition with regular expressions.

You can define as many token constraints as you want, each of which should be on a new line.

You can freely combine all available restriction options URL's, URL parameters, and JSON data in the body.

[method].*/rest/api/.*[QueryParam::paramName==Regexp][JsonData::nodeName==Regexp]

URL without any other restrictions

Example:

Restriction to all space endpoints

.*/rest/api/space.*

URL with POST method restriction

Example:

Restriction to set property endpoint on space with key EXTENDER (only POST method)

[post].*/rest/api/space/EXTENDER/property.*

URL with parameters

Add an additional definition to the end of the “Limit to” definition as shown in the example

[QueryParam::URL_PARAM_NAME==REGEXP]

where URL_PARAM NAME is the name of the URL parameter
where REGEXP is the definition of a regular expression, what value the URL parameter can take

Example:

Restriction to find pages (only for space key starting with PM)

.*/rest/api/content/scan[QueryParam::spaceKey==PM.*]

Restriction to find a page by title (only for space key ending with PM + you can expand only history)

.*rest/api/content[QueryParam::spaceKey==.*PM][QueryParam::expand==history]

URL with JSON data in the body

Add an additional definition to the end of the “Limit to” definition as shown in the example

[JsonData::JSON_NODE_NAME==REGEXP]

where JSON_NODE_NAME NAME is the name of the JSON node name
where REGEXP is the definition of a regular expression, what value the JSON node name can take

Example:

Method: POST

URL: {CONFLUENCE_URL}/rest/api/content/

Request JSON:

{
    "type": "page",
    "title": "My Test Page",
    "space": {
        "key": "TST"
    },
    "body": {
        "storage": {
            "value": "<p>This is a new page</p>",
            "representation": "storage"
        }
    }
}

Restriction to create new page (you can create only page content)

.*/rest/api/content/[JsonData::type==page]

Restriction to create new page (you can create only page content + page must begin with the words TEST)

.*/rest/api/content/[JsonData::type==page][JsonData::title==TEST.*]

Secure mode

We created this mode to add another layer of security to your tokens and allow you to better protect them.

In this mode you will notice several differences from the standard mode:

you will only see the token once, you will not be able to see it again
you will not be able to view the code snippet, change the expiration date, edit restrictions or any other Token data

Standard mode	Secure mode

Standard mode	Secure mode

How to turn on Secure mode

Keep in mind that this setting is universal across Confluence and will require shutting down the instance. As always, we recommend testing changes in a lower environment before attempting them in production.

Shutdown Confluence. Even on Confluence Data Center, it is necessary to shutdown all nodes. A rolling restart of the nodes won't suffice.
Edit the confluence.cfg.xml file in your Confluence home directory
Change the value of the extender.token.secure.mode property within this file and set it to true
If this property does not appear in the confluence.cfg.xml file, add it to the file just before the </properties> tag
<property name="extender.token.secure.mode">true</property>

<?xml version="1.0" encoding="UTF-8"?>

<confluence-configuration>
  <setupStep>complete</setupStep>
  <setupType>install</setupType>
  <buildNumber>8301</buildNumber>
  <properties>
    <property name="access.mode">READ_WRITE</property>
    <property name="admin.ui.allow.daily.backup.custom.location">false</property>
    <property name="admin.ui.allow.manual.backup.download">false</property>
    <property name="admin.ui.allow.site.support.email">false</property>
    <property name="atlassian.license.message">KEY0987</property>
    <property name="attachments.dir">${confluenceHome}/attachments</property>
    <property name="confluence.setup.server.id">AAAA-BBBB-CCCC-DDDD</property>
    <property name="confluence.webapp.context.path">/confluence</property>
    <property name="hibernate.c3p0.acquire_increment">1</property>
    <property name="hibernate.c3p0.idle_test_period">100</property>
    <property name="hibernate.c3p0.max_size">60</property>
    <property name="hibernate.c3p0.max_statements">0</property>
    <property name="hibernate.c3p0.min_size">20</property>
    <property name="hibernate.c3p0.timeout">30</property>
    <property name="hibernate.connection.driver_class">org.h2.Driver</property>
    <property name="hibernate.connection.isolation">2</property>
    <property name="hibernate.connection.password"></property>
    <property name="hibernate.connection.username">sa</property>
    <property name="hibernate.database.lower_non_ascii_supported">true</property>
    <property name="hibernate.dialect">org.hibernate.dialect.H2Dialect</property>
    <property name="hibernate.schema_management_tool">com.atlassian.confluence.impl.hibernate.ConfluenceHibernateSchemaManagementTool</property>
    <property name="hibernate.setup">true</property>
    <property name="jwt.private.key">KEY321</property>
    <property name="jwt.public.key">KEY123</property>
    <property name="lucene.index.dir">${localHome}/index</property>
    <property name="synchrony.btf">true</property>
    <property name="synchrony.encryption.disabled">true</property>
    <property name="synchrony.proxy.enabled">false</property>
    <property name="webwork.multipart.saveDir">${localHome}/temp</property>
    <property name="extender.token.secure.mode">true</property>
  </properties>
</confluence-configuration>

Save the updated confluence.cfg.xml file.
Restart Confluence.

REST API

Available ONLY for Confluence administrators

Get all Tokens

Method type: GET

URL: {CONFLUENCE_URL}/rest/extender/1.0/tokenTools/get

Respons format: JSON

Example response:

{
  "tokens": [
    {
      "label": "Token name",
      "user": "admin",
      "token": "ip9ul19f8jenb92tji8lo34qt7tb1meo",
      "limitTo": "[post].*/rest/api/space/EXTENDER/property.*<br>.*/rest/api/space.*",
      "ip": "",
      "validUntil": 1630476718964,
      "dateCreated": 1622700718964,
      "counter": 100
    },
    {
      "label": "Token name two",
      "user": "jankowalski",
      "token": "okf8a73basc74nasc9n32",
      "limitTo": "",
      "ip": "192.168.1.1",
      "validUntil": 1630476718964,
      "dateCreated": 1622700718964,
      "counter": 123456
    }
  ],
  "status": "ok"
}

Create Token

Method type: POST

URL: {CONFLUENCE_URL}/rest/extender/1.0/tokenTools/set

Request format: JSON

Example request:

{
  "label": "Token name",
  "daysUntilExpiry": 90
  "userName": "admin",
  "limitTo": "[post].*/rest/api/space/EXTENDER/property.*\n.*/rest/api/space.*"
  "token": "ip9ul19f8jenb92tji8lo34qt7tb1meo"
}

{
  "label": "Token name",
  "daysUntilExpiry": 0
  "token": "ip9ul19f8jenb92tji8lo34qt7tb1meo"
}

{
  "label": "Token name",
  "userName": "admin"
}

label - required - token name

daysUntilExpiry - optional - for security reasons, you can set this token to automatically expire. You can't change the expiry date once the token is created.

userName - optional - a user who will be able to use token, leave this field empty so that anyone can use the token.

limitTo - optional - you can limit the token to specific urls and methods, you can add new line sign using \n, \\n or <br>

token - optional - token, leave this field empty and the system will generate a random string

Delete Token

Method type: DELETE

URL: {CONFLUENCE_URL}/rest/extender/1.0/tokenTools/delete

Request format: JSON

Example request:

{
  "token": "ip9ul19f8jenb92tji8lo34qt7tb1meo"
}

Disable/Enable "Usage Details" data collection

Method type: POST

URL: {CONFLUENCE_URL}/rest/extender/1.0/tokenTools/set

Request format: JSON

Example request:

{
    "collectUsageDetails": false
}

{
    "collectUsageDetails": true
}

Disable/Enable adding token calls to the audit log

Method type: POST

URL: {CONFLUENCE_URL}/rest/extender/1.0/tokenTools/set

Request format: JSON

Example request:

{
    "addAuditRecord": false
}

{
    "addAuditRecord": true
}

Changes

REST API Tokens is available since v. 2.6.*

Since v. 2.10.*

changes in supported endpoint URLs - CONFLUENCE_URL/rest/*
added tokens expiration functionality
added the ability to specify token restrictions for URLs/methods

Since v. 2.16.*

added public API for administrators

Since v. 2.27.*

added two new endpoints
- Disable/Enable "Usage Details" data collection
- Disable/Enable adding token calls to the audit log

Since v. 3.14.*

Specify limits for tokens - added the ability to define restrictions on URL parameters and JSON data in the body

Since v. 3.17.*

Added Secure mode - additional security layer for Tokens