General information

A primary use case for API tokens is to allow scripts to access REST APIs for Confluence applications using Basic Auth or Bearer Token with extended filtering/blocking capabilities.

If you define a token for a user, only that user can use it (if you use Basic Auth or Bearer Token), but if you do not specify a user, any user will be able to use this token (only if you use Basic Auth)

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 the option Restrict tokens only for Extender endpoints in configuration

CONFLUENCE_URL/rest/extender/*

Token Authentication

You can change the supported authorization methods for all generated tokens between Basic Auth and Bearer Token, or be compatible with both. The default type is Basic Auth.

Basic Auth
Basic authentication is a simple and widely supported authentication method that uses the HTTP header to send the username and password of the client. The client encodes the credentials in base64 and sends them with every request. The server decodes the credentials and checks if they are valid. Basic authentication is easy to implement and compatible with most clients, but it has some drawbacks. The credentials are not encrypted, so they can be intercepted by malicious actors. The client has to store the credentials securely and send them repeatedly, which can affect the performance and security of the API. Basic authentication is suitable for simple and low-risk scenarios, such as testing or prototyping.

Bearer Token authentication
Bearer authentication is a more advanced and secure authentication method that uses tokens instead of credentials. A token is a string of characters that represents the identity and permissions of the client. The client obtains a token from an authentication server by providing valid credentials or other information. The client then sends the token with every request using the HTTP header or the query string. The server validates the token and grants access to the API. Bearer authentication has several advantages over basic authentication. The token is encrypted, so it cannot be tampered with or stolen. The client does not have to store or send the credentials, which reduces the risk of exposure and improves the performance of the API. The token can also have an expiration date, which limits the duration of the access. Bearer authentication is suitable for complex and high-risk scenarios, such as production or public APIs.

How to choose?
When choosing between basic and bearer authentication for an API, there is no one-size-fits-all answer. It depends on the API's requirements, design, and security level. When making a decision, consider factors such as compatibility, complexity, and security. For example, if the API needs to support a wide range of clients, basic authentication may be more convenient. However, if the API needs to integrate with third-party services or platforms, bearer authentication may be more compatible. Additionally, if the API is simple and has few endpoints and resources, basic authentication may be sufficient. On the other hand, if the API is complex and has many endpoints and resources, bearer authentication may be more scalable. Moreover, if the API is low-risk and does not handle sensitive or personal data, basic authentication may be acceptable with HTTPS encryption. Lastly, if the API is high-risk and handles sensitive or personal data, bearer authentication may be mandatory for better security and control over access and data protection.

Source - How do you choose between basic and bearer authentication for your API?

Code snippet

You can generate the code snippet (JavaScript/curl) and authentication data for calls by clicking the 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 username.
TOKEN here is token generated in REST API Tokens page

CURL Example

Basic Auth

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

curl -H 'Authorization: Basic YWRtaW46cGhuN2dkNHY2cWcyNGZ2aGZwNnFwZ2psa3VwMDFnMGxn' CONFLUENCE_URL/localhost:1990/confluence/rest/api/content

Bearer Token

curl -H 'Authorization: Bearer phn7gd4v6qg24fvhfp6qpgjlkup01g0lg' CONFLUENCE_URL/confluence/rest/api/content

Postman Example

Basic Auth

Note that :

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

Bearer Token

Note that :

Bearer Token use this type on Authorization type
Token here is the unique token

Specify limits for tokens

You can restrict the token to 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 a 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 a 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 can the URL parameter 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 a 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 can the JSON node name 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 the 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
}

Troubleshooting

Problem	Resolution

Problem

Resolution

curl request (POST, PUT) return error code 3XX and response

{
  "statusCode": 500,
  "message": "",
  "reason": "Internal Server Error"
}

Server reports that the requested page has moved to a different location. When curl follows a redirect, and if the request is a POST, it sends the following request with a GET if the HTTP response was 301, 302, or 303. If the response code was any other 3xx code, curl resends the following request using the same unmodified method.

Please check -L, --location documentation and add extra options to your request, like --post301, --post302 or --post303.

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