Cloud API

The Layer5 Cloud REST API lets you build integrations, retrieve data, and automate your infrastructure. This page states the conventions every endpoint shares: base URL, authentication, organization context, pagination, and errors. For the list of endpoints, see the REST API Reference.

Base URL 🔗

Every endpoint lives under /api on the host of your Layer5 Cloud deployment.

Authentication 🔗

Authenticate with a security token. Send it as a bearer token in the Authorization header:

curl https://cloud.layer5.io/api/identity/users/profile \
  -H "Authorization: Bearer <token>"

When a request has no Authorization header, Layer5 Cloud reads the browser session cookie instead. Scripts and integrations always send the header.

A token belongs to your user account, not to an organization. One token reaches every organization you are a member of, the way a GitHub personal access token reaches every repository its owner can. A request with a missing or invalid credential receives HTTP 401.

What a token can do is the same as what you can do: every guarded endpoint checks that you hold the required permission in the organization the request runs in. See Roles and Permissions.

Organization context 🔗

A guarded request runs in one organization. Layer5 Cloud resolves the organization from these sources, in this order:

1. The request’s host. A request that arrives on an organization’s custom domain runs in that organization, and the sources below are not consulted. Requests to the deployment’s own address skip this step.
2. The X-Current-Orgid request header.
3. The organization saved in your user preferences.
4. The organization saved in your browser session (browser clients only).

Header names are case-insensitive. The first source that holds a value wins.

• cURL
• JavaScript
• Python

curl -X GET "https://cloud.layer5.io/api/environments" \
  -H "Authorization: Bearer <Your-Token>" \
  -H "X-Current-Orgid: <Your-Organization-ID>"

const res = await fetch("https://cloud.layer5.io/api/environments", {
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Current-Orgid": orgId,
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://cloud.layer5.io/api/environments",
    headers={
        "Authorization": "Bearer <Your-Token>",
        "X-Current-Orgid": "<Your-Organization-ID>",
    },
)
print(res.json())

Save a default organization and workspace 🔗

To make an organization the default for every request that omits the header, save it in your user preferences:

curl -X PUT "https://cloud.layer5.io/api/identity/users/preferences" \
  -H "Authorization: Bearer <Your-Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedOrganizationId": "<Your-Organization-ID>",
    "selectedWorkspaceForOrganizations": {
      "<Your-Organization-ID>": "<Your-Workspace-ID>"
    }
  }'

• selectedOrganizationId is the default organization. The key is case-insensitive.
• selectedWorkspaceForOrganizations maps an organization ID to the workspace that receives the designs you save in it. When an organization has no saved workspace, Layer5 Cloud uses the first workspace available.
• A preference key that the request does not mention keeps its stored value. A key the server does not recognize, such as selectedOrganization, is ignored.
• You cannot change your badges through this endpoint.

Pagination 🔗

List endpoints that paginate accept these query parameters.

The response carries the current page, the page size, the total count, and the array of items.

Errors 🔗

An error response is identified by its HTTP status code. The body takes one of three shapes, depending on the endpoint.

Branch on the status code first, then parse the body defensively. The generated REST API Reference documents 401 responses as plain text, but the authentication layer answers with JSON.

Example: count Academy registrations 🔗

The Academy curricula endpoint is public. It needs no token. It returns curricula, each with its registration count.

• cURL
• Python

curl -s "https://cloud.layer5.io/api/academy/curricula" \
  | jq '[.data[].registration_count] | add'

import requests

res = requests.get("https://cloud.layer5.io/api/academy/curricula")
total = sum(item["registration_count"] for item in res.json()["data"])
print(total)

The result is a single number, the total registrations across the curricula returned.

Related Reading

• API Reference
• Security Reference
• Workspace and Environment Reference
• Feature Availability by Plan
• Feature Availability by Plan
• Help and Support