> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# UpCloud API Credentials

> Store an UpCloud API token in Ankra to provision and manage UpCloud server clusters and UpCloud Managed Kubernetes (UKS).

UpCloud API credentials store an UpCloud API token, used to provision and manage self-managed [UpCloud clusters](/guides/upcloud-clusters) and [UpCloud Managed Kubernetes (UKS)](/guides/uks-clusters). The token is validated when you save it - Ankra makes a read-only call to the UpCloud API (`GET /account`), so a rejected or mistyped token is refused immediately.

## What Ankra Accesses

One token covers both cluster types. For self-managed UpCloud clusters, Ankra provisions the infrastructure directly:

| Resource          | Operations                               | Why it's used                                                                        |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------ |
| Servers           | create, read, start/stop/restart, delete | The cluster's nodes and bastion                                                      |
| SDN networks      | create, read, update, delete             | The cluster's private network                                                        |
| Routers           | create, read, delete                     | Attach the private network                                                           |
| Gateways          | create, read, delete                     | Outbound internet access (NAT) for private nodes                                     |
| Storage templates | read                                     | The OS image for new servers                                                         |
| Load balancers    | read, delete                             | Created by Kubernetes itself - Ankra only cleans them up when you delete the cluster |

For [UKS](/guides/uks-clusters), Ankra uses the managed Kubernetes API instead:

| Resource                            | Operations                   | Why it's used                                                      |
| ----------------------------------- | ---------------------------- | ------------------------------------------------------------------ |
| Kubernetes clusters (`/kubernetes`) | create, read, delete         | UKS cluster lifecycle                                              |
| Node groups                         | create, read, update, delete | Scale and manage the cluster's node groups                         |
| Kubeconfig                          | read                         | Connect Ankra's agent to the cluster                               |
| Versions, plans, zones              | read                         | Available Kubernetes versions, node plans, and zones in the wizard |

## Creating an UpCloud API Credential

<Steps>
  <Step title="Create an UpCloud API token">
    1. Log in to the [UpCloud Control Panel](https://hub.upcloud.com)
    2. Go to **Account** → **API tokens** (for a scoped identity, first create a workspace member under **People** with **API connections** allowed, and create the token as that member)
    3. Create a token and copy it (prefixed with `ucat_`; shown once)

    The token inherits the permissions of the account it belongs to - that account must be allowed to manage servers, networking, storage, and Kubernetes. A read-only or restricted member's token passes the save-time check but fails when Ankra provisions.
  </Step>

  <Step title="Add to Ankra (UI)">
    Go to **Credentials** → **Add** → **UpCloud**, then provide:

    * **Name**: a unique identifier - lowercase letters and numbers only, cannot start with a hyphen (e.g. `upcloud-prod`)
    * **API Token**: the `ucat_...` token from the previous step

    Click **Test connection** to verify the token against the UpCloud API, then save.
  </Step>

  <Step title="Or via CLI">
    ```bash theme={null}
    ankra credentials upcloud create --name my-upcloud
    # You will be securely prompted for the API token
    ```
  </Step>
</Steps>

For self-managed UpCloud clusters you also need an [SSH key credential](/platform/credentials/ssh-key) - create one with `ankra credentials upcloud ssh-key create --name my-key --generate`.

<Note>
  The token can be rotated later from the credential's page without recreating the credential - everything using it picks up the new token automatically.
</Note>

## Listing UpCloud Credentials

<CodeGroup>
  ```bash CLI theme={null}
  ankra credentials upcloud list
  ```

  ```bash cURL theme={null}
  curl https://platform.ankra.app/api/v1/credentials/upcloud \
    -H "Authorization: Bearer $ANKRA_API_TOKEN"
  ```
</CodeGroup>

## Troubleshooting UpCloud Credentials

The table below covers the **Test connection** result in the Ankra UI:

| Test connection result           | Cause                                                              | Solution                                                                          |
| -------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| UpCloud rejected the API token.  | The token is invalid, revoked, expired, or was copied incompletely | Create a new token and paste the full `ucat_...` value                            |
| Could not reach the UpCloud API. | Network or connectivity issue                                      | Retry; ensure outbound access to `api.upcloud.com`                                |
| UpCloud returned HTTP `<code>`.  | Unexpected UpCloud-side response                                   | Retry; check the [UpCloud status page](https://status.upcloud.com) if it persists |

**Test connection** verifies the token is accepted, not what its account may manage. If the credential saves fine but provisioning later fails with a permissions error, the token's account is restricted - allow it to manage servers, networking, storage, and Kubernetes, or create a token for a less restricted account and rotate it in on the credential's page.