Skip to content

Resource model

The reference lists endpoints one at a time. This page is the shape they form — what each resource is, what it belongs to, and the order you meet them in.

The shape

Customer                        your organisation's tenancy
└── Project                     a workspace within it
    ├── Virtual machines        compute
    ├── Networks                addressing, per cluster
    │   └── IPv4 addresses      assigned to machines
    └── SSH keys                how you log in

Users        hold a role on a customer or a project
Devices      hold the tokens your clients authenticate with
Info         the catalogue you build from — clusters, flavours, images

Tenancy: customers and projects

A customer is the top-level tenancy — normally your organisation. A project subdivides it, and is where day-to-day resources live.

Both are tenants, which is why so many paths take a {tenantUUID}: SSH keys, networks, IPv4 addresses and machines are all addressed by the tenant that owns them, whether that is a customer or a project.
Customers List, read, update and delete the ones you can see. Creating a customer is not self-service — it happens when your organisation is onboarded.
Projects Full lifecycle. A project is created against a customer_id, so you always know which tenancy it belongs to.

Which customers and projects you can see is decided by your role, not by a filter you pass. Two people calling GET /v2/projects legitimately get different lists.

People and access: users, roles, policies

A user is an identity that has been invited into a customer or project. A role is what that identity may do there. A policy is the definition behind a role — which permissions it carries.

The important part is that a role is held within a tenancy, not globally: the same person can administer one project and only read another.

You can read your own record, list the people in a tenancy you administer, invite people into it, and change their roles. Role and policy definitions themselves are administered by Taiga Cloud and are not part of this API — you work with their effects rather than editing them.

Access failures look like absence

A resource your role does not reach answers 404, not 403, so it is not disclosed. A 404 on an identifier you believe is valid is usually a role question.

The catalogue: info

Before creating anything you need to know what exists to create it from.
Clusters Where compute runs. Everything is created into one.
Flavours Machine sizes — CPU, memory, GPU.
Images Operating system images to boot from.

These are read-only and shared. Fetch them first: the identifiers they return are what the creation calls expect.

Compute: virtual machines

A machine is the point where everything else meets. Creating one names a flavour, an image, a cluster, a tenant, a network, and the SSH keys that may log in — so the other resources have to exist first.

Once running, a machine has more than a record:
Status Start, stop and restart it.
Console Reach it without the network path working.
Config Read and update its configuration.
Metrics Utilisation over time.
Activity What has happened to it, and when.

Networking: networks, IPv4, IPv6

A network belongs to a cluster and a tenant — created against both, since addressing is cluster-local.

IPv4 addresses are resources in their own right: created, assigned, updated and deleted, and attached to machines. IPv6 is different — it arrives as properties of the network (prefix6, assigned_addresses6) rather than as something you create. There are no IPv6 endpoints; you read the network to see what it has.

Access artefacts: devices

Every completed device code flow registers a device holding the tokens it issued. Devices are not created directly — they appear as a by-product of authenticating.

They are worth revisiting: list them to see what holds credentials, and revoke anything belonging to a machine you have decommissioned or do not recognise.

Putting it together

A first deployment, in dependency order:

  1. Read the catalogue — pick a cluster, a flavour and an image
  2. Have a project — create one against your customer, or use an existing one
  3. Add an SSH key to that tenant, so you can log in later
  4. Create a network on the chosen cluster for that tenant
  5. Create the machine, naming the flavour, image, cluster, tenant, network and key
  6. Assign an IPv4 address if it needs to be reachable
  7. Watch it through status, console, metrics and activity

Each step supplies an identifier the next one needs, which is why the order matters more than it first appears. Exact fields for each call are in /reference.