API tokens

This chapter focuses on services for the personal API tokens.

get Get personal API tokens

A GET to /tokens returns the personal API token list for the authenticated user.

HTTP request

GET /api/rest/latest/tokens HTTP/1.1
Accept: application/json
Host: localhost:8080

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1264

{
  "_embedded" : {
    "api-tokens" : [ {
      "id" : 1,
      "uuid" : "f8e2f2d8-0fbf-4d29-8003-b729bfe212c8",
      "user" : {
        "_type" : "user",
        "id" : 4
      },
      "name" : "token 1",
      "createdOn" : "2024-06-15T07:48:02.000+00:00",
      "createdBy" : "user1",
      "expiryDate" : "2025-02-03",
      "lastUsage" : "2024-06-28T09:54:27.000+00:00",
      "permissions" : "READ",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/tokens"
        }
      }
    }, {
      "id" : 2,
      "uuid" : "9e02ea67-f7ae-4c22-80c5-cb6bd64d1786",
      "user" : {
        "_type" : "user",
        "id" : 4
      },
      "name" : "token 2",
      "createdOn" : "2024-05-02T13:18:14.000+00:00",
      "createdBy" : "user2",
      "expiryDate" : "2024-12-28",
      "lastUsage" : "2024-06-10T16:00:07.000+00:00",
      "permissions" : "READ-WRITE",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/tokens"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/tokens?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Response fields

Path Type Description

_embedded.api-tokens

Array

the personal API tokens of the user

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements the user is allowed to read

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

post Create a personal API token

A POST to /tokens creates a new personal API token for the user who performs the request.

HTTP request

POST /api/rest/latest/tokens HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 97
Host: localhost:8080

{
  "name" : "token read write",
  "permissions" : "READ_WRITE",
  "expiry_date" : "2025-05-06"
}

Request fields

Path Type Description

name

String

the name of the personal API token (maximum 255 characters)

permissions

String

the permissions for the token ('READ' or 'READ_WRITE')

expiry_date

String

the expiry date for the token in the format 'YYYY-MM-DD' (it cannot exceed one year)

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 1000

{
  "id" : 6,
  "uuid" : "9e02ea67-f7ae-4c22-80c5-cb6bd64d1786",
  "user" : {
    "_type" : "user",
    "id" : 4,
    "first_name" : "",
    "last_name" : null,
    "login" : null,
    "email" : "",
    "active" : true,
    "group" : null,
    "can_delete_from_front" : true,
    "teams" : [ ],
    "last_connected_on" : null,
    "created_by" : "admin",
    "created_on" : "2017-07-04T10:00:00.000+00:00",
    "last_modified_by" : "admin",
    "last_modified_on" : "2017-07-05T10:00:00.000+00:00"
  },
  "name" : "token read write",
  "permissions" : "READ_WRITE",
  "expiry_date" : "2025-05-06T00:00:00.000+00:00",
  "created_on" : "2024-07-02T13:18:14.000+00:00",
  "created_by" : "user1",
  "last_usage" : null,
  "generated_token" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxIiwidXVpZCI6IjBmZmUxODdmLTAxYzctNGViZC05NjY5LWI0ODFlNzEyMGE1ZiIsInBlcm1pc3Npb25zIjoiUkVBRCIsImlhdCI6MTcyMTMwODc4OSwiZXhwIjoxNzUyNTM3NjAwfQ.qWlfn0D4R5-5PXwTpkArmjY2NOjpcE50dzwlaXkNbRu0K8CRS7YO-xsjPegup73nKxYQBQvbYJ_EPnTURRFQng"
}

Response fields

Path Type Description

id

Number

the ID of the personal API token

user

Object

the user who owns the API token

uuid

String

the UUID of the API token

name

String

the name of the API token

created_on

String

the date when the API token was created

created_by

String

the user who has created the token

permissions

String

the permissions associated with the API token

expiry_date

String

the expiry date of the API token

last_usage

String

the date when the token was last used

generated_token

String

the generated token that the user should keep secret

delete Delete a personal API token

A DELETE to /tokens/{id} deletes the token with the given id.

HTTP request

DELETE /api/rest/latest/tokens/3 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

HTTP response

HTTP/1.1 204 No Content

delete Self-destroy a personal API token

A DELETE to /tokens/self permanently deletes the personal API token used to perform this request.

This endpoint aims at managing leaked tokens, allowing a person or a secret detection script to delete a token that may have been exposed in a Git repository, a document, or other locations. It does not consider read or read/write permissions; the token used for calling it will be deleted even if it is a read-only token.

It returns a 200 status code if the operation is successful. If no token is provided, the token is invalid, or basic authentication is used, it returns a 401 status code.

HTTP Request

DELETE /api/rest/latest/tokens/self HTTP/1.1
Accept: application/json
Host: localhost:8080