23. API Tokens

UpCloud API calls can be authenticated with HTTP Bearer (token) authentication. The token API requests below allow creation, management and deletion of bearer tokens.

The bearer token can be used for authentication by setting the Authorization header of the API request:

Authorization: Bearer ucat_01DQE3AJDEBFEKECFM558TGH2F

Create token

Create a new bearer token. Maximum token validity is 365*24=8760 hours.

Request

POST /1.3/account/tokens HTTP/1.1

{
  "name": "token",
  "expires_at": "2025-11-30T08:03:15.944Z",
  "allowed_ip_ranges": [
    "0.0.0.0/0",
    "::/0"
  ]
}

Attribute allowed_ip_ranges allows defining a list of CIDR/IP addresses from where the token is accepted. Empty list denies access from everywhere. If unset, the default list will be the IP filters of the account. If no IP filters are defined for the account either, the default will be ["0.0.0.0/0", "::0/0"], i.e. allow from any address.

Request attributes

Attribute	Accepted value	Required	Description
name	1-1024 characters	yes	The name of the token.
expires_at	RFC 3339 timestamp	yes	Token expiry time. Must be in the future and up to 24h*365=8760h.
expires_in	Duration string	no	The requested duration until expiry of the token, e.g. '1h30min'. Needs to be a positive duration and maximum of 8760h. Can be used instead of `expires_at`. Supported units are 'h' for hours, 'm' for minutes and 's' for seconds.
can_create_tokens	true/false	no	Allow token to be used to create new tokens. Default false.
allowed_ip_ranges	An array of 0-100 CIDR/IP addresses	no	Optional whitelist for IP/CIDR addresses from where the token is accepted. Empty list denies access from anywhere. Default: account IP filters.

Normal response

HTTP/1.1 201 Created

{
  "token": "ucat_01DQE3AJDEBFEKECFM558TGH2F",
  "id": "0c8bc50b-968e-4dc3-b9c2-1a4a5298b652",
  "name": "token",
  "created_at": "2025-04-02T11:24:25.10281Z",
  "expires_at": "2025-11-30T08:03:15.944005Z",
  "can_create_tokens": true,
  "allowed_ip_ranges": [
    "0.0.0.0/0",
    "::/0"
  ],
  "gui": false
}

Response attributes

Attribute	Description
token	The bearer token. Only available when creating a new token.
id	The id of the token. Used in the Get token details and Delete token request.
name	The bearer token name.
created_at	Token creation time.
expires_at	Token expiry time.
can_create_tokens	Allow token to be used to create new tokens.
allowed_ip_ranges	IP/CIDR addresses from where the token is accepted.
gui	Tokens created when logging in to hub.upcloud.com. Hub uses these tokens to manipulate resources when user operates the hub.

Error responses

HTTP status	Description
400 Bad request	Request attribute failed validation.
401 Unauthorized	Authentication failed.
403 Forbidden	Forbidden, the token used to authenticate is not allowed to create tokens.

Get token details

Show details of a token by id.

Request

GET /1.3/account/tokens/{id} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "id": "0c0f1d0e-ccba-48bf-a2c2-b267e8a58597",
  "name": "token",
  "created_at": "2025-04-04T08:27:27.603019Z",
  "expires_at": "2025-11-30T08:03:15.944017Z",
  "last_used_at": "2025-04-04T08:38:20.890805Z",
  "can_create_tokens": true,
  "allowed_ip_ranges": [
    "0.0.0.0/0",
    "::/0"
  ],
  "gui": false
}

Response attributes

Attribute	Description
id	The id of the token. Used in the Get token details and Delete token request.
name	The bearer token name.
created_at	Token creation time.
expires_at	Token expiry time.
last_used_at	Time the token was last used for authentication.
can_create_tokens	Allow token to be used to create new tokens.
allowed_ip_ranges	IP/CIDR addresses from where the token is accepted.
gui	Tokens created when logging in to hub.upcloud.com. Hub uses these tokens to manipulate resources when user operates the hub.

Delete token

Deletes the specified token.

Request

DELETE /1.3/account/tokens/{id} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status	Description
404 Not Found	Token not found.

List tokens

Returns a list of all tokens.

Request

GET /1.3/account/tokens?limit={limit}&offset={offset} HTTP/1.1

Request attributes (query parameters)

Attribute	Accepted value	Default value	Required	Description
limit	1-100	20	no	Number of entries to receive at most.
offset	0-	0	no	Offset for retrieved results.
sort	`created_at`, `expires_at`, `last_used_at` or `name`	`-created_at`	no	Sort order. Can be prefixed with `+` for ascending or `-` for descending order, e.g, `-name`.
gui	true/false	(not set)	no	Filter hub.upcloud.com session API tokens. `true` returns session API tokens only, `false` returns non-session API tokens only. Don't specify any value to fetch both.

Normal response

HTTP/1.1 200 OK

[
  {
    "id": "0c848138-2559-4562-9520-b1f22c4ae751",
    "name": "token",
    "created_at": "2025-03-25T13:46:19.502878Z",
    "expires_at": "2025-03-25T14:16:19.502644Z",
    "can_create_tokens": true,
    "allowed_ip_ranges": [
      "1.2.3.4"
    ],
    "gui": false
  },
  {
    "id": "0cc50c9d-6a81-494b-af8c-f7271cfd4d22",
    "name": "token",
    "created_at": "2025-03-25T14:12:06.534789Z",
    "expires_at": "2025-03-25T14:42:06.534342Z",
    "last_used_at": "2025-03-25T14:12:33.000692Z",
    "can_create_tokens": true,
    "allowed_ip_ranges": [
      "1.2.3.4"
    ],
    "gui": false
  }
]