Skip to content

24. API Tokens

This is a beta feature, please contact us if you have questions or run into any problems!

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

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
    }
]