Your first request

You need an API client, which is a credential that belongs to your tenant rather than to you. It authenticates with a client id and secret, exchanges those for a short access token, and carries only the permissions you grant it.

First, pick a zone. There is no single API host: each availability zone is a separate deployment and a resource exists in exactly one of them. One zone is live today, so every example below uses it.

export INTERLAKEN_API=https://api.eu-par-1.interlaken.ai

The current list is at interlaken.ai/zones.json; Availability zones explains the model.

Create an API client

In the console, open Settings → API clients and create one. Give it a name and tick only the permissions it needs. Or do it over the API, with a token you already have:

curl -sX POST $INTERLAKEN_API/api/v1/api-clients \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"deploy-bot","scopes":["vms:read","vms:create"]}'

The response carries client_id and client_secret. The secret is shown once and never again. If you lose it, rotate the client rather than creating a new one.

{
  "id": "8f2c…",
  "client_id": "ic_…",
  "client_secret": "ics_…",
  "secret_hint": "…a91f",
  "token_endpoint": "https://api.eu-par-1.interlaken.ai/oauth/token",
  "scopes": ["vms:read", "vms:create"]
}

Exchange the secret for a token

export INTERLAKEN_CLIENT_ID=ic_…
export INTERLAKEN_CLIENT_SECRET=ics_…

curl -s "$INTERLAKEN_API/oauth/token" \
  -u "$INTERLAKEN_CLIENT_ID:$INTERLAKEN_CLIENT_SECRET" \
  -d grant_type=client_credentials

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "vms:read vms:create"
}

The token lasts an hour. There is no refresh token on this grant: when it expires, ask for another one. Authentication covers the other grants.

Call the API

curl -s $INTERLAKEN_API/api/v1/vms \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{ "items": [], "total": 0 }

An empty list is a successful call. If you get 403, read the required_permission field in the body: it names exactly the key the route wanted.

Create something

curl -sX POST $INTERLAKEN_API/api/v1/vms \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"web-1","instance_type":"…","image_id":"…"}'

The call returns an id as soon as the intent is recorded, not when the machine is running. Poll GET /api/v1/vms/{id} and watch status settle, or subscribe to /api/v1/events. Create a VM documents the whole request body, and the instance types and images available to you come from GET /api/v1/instance-types and GET /api/v1/images.

Do the same thing with the CLI

The interlaken command wraps exactly this flow, keeps the token fresh and lets you hold one profile per availability zone.

interlaken login --api "$INTERLAKEN_API" \
  --client-id "$INTERLAKEN_CLIENT_ID" --client-secret "$INTERLAKEN_CLIENT_SECRET"
interlaken api GET /api/v1/vms

See The interlaken CLI.

Create an API client

Exchange the secret for a token

Call the API

Create something

Do the same thing with the CLI

Next

Permissions and scopes

Pagination, filtering and sorting

Errors

On this page