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.

Image Added

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

Image Added

Image Added

Image Added

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

Image Removed

Image Added

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

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 supported URLs/methods for tokens

You can limit the token to specific urls and methods. Provide endpoint url with regular expression, add (or not) method restriction.

You can define any number of token restrictions, each of which should be on a new line.

Examples:

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

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

• Restriction to all space endpoints (for all methods)

.*/rest/api/space.*

REST API

Get all Tokens

Method type: 

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: 

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 - 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: 

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

Request format: JSON

Example request:

{
  "token": "ip9ul19f8jenb92tji8lo34qt7tb1meo"
}

Changes