Getting started

Overview

The Platform API Gateway is one entry point for every Jamf API. You create one integration in Jamf Account, grant it the capabilities it needs, and use it to call blueprints, device inventory, Jamf Pro, Jamf Security Cloud, and the rest of the platform. One set of credentials and one permission model covers all of them.

This article covers creating an integration and making your first authenticated request. Everything that applies to every API behind the gateway, including regions, permissions, pagination, and errors, is in Platform API fundamentals.

What you need

Before you begin, make sure you have:

• Access to Jamf Account for your organization, with the Administrator role or a custom role with Integrations privileges
• At least one Jamf product tenant associated with your organization
• A platform environment containing at least one of those tenants, if you plan to call platform APIs

Choose a scope level

Every integration is scoped to one level. The level you pick decides which APIs you can reach and which permissions are available to grant.

A platform environment is a defined group of tenants that your organization has across the Jamf platform. It links resources and capabilities across products, which is why platform APIs work only at the environment level.

Create your first integration

An integration defines what you can reach, what you're allowed to do, and holds the client ID and secret you authenticate with.

1. Sign in to Jamf Account and select Integrations from the left navigation.
2. Click Create integration and give it a name and, optionally, a description.
3. Set the scope level to organization management, platform environment, or tenant. Then select the organization, environment(s), or tenant(s) it applies to.
4. Assign permissions by browsing through capabilities. Grant only what your integration needs.
5. Click Create integration to save.

The permissions on offer depend on what you selected in step 3, so the list shows only the capabilities your tenants support.

Jamf Account then displays your client ID and client secret, along with a ready-to-use curl command.

Integrations are valid for six months. Plan for rotation as part of your build.

Find your base URL

Which host you call depends on your scope level.

{region} is us, eu, or apac, matching the region your product instances are hosted in. Organization management uses the bare host, which always routes to the US region.

Endpoint paths follow a single pattern:

/{domain-namespace}/v{n}/{resource-path}

The version segment is required.

Pass context in headers

Tenant and environment IDs travel in headers rather than the URL path:

Organization management requests need no context header. A token belongs to exactly one organization, so the gateway resolves it from the token itself.

To find an ID, open your integration in Jamf Account and click a tenant or environment pill in the Integration details panel to copy the ID to your clipboard.

Request an access token

An access token is a short-lived credential you exchange your client ID and secret for, then pass in the Authorization header of every API request.

Post your credentials as form fields to the token endpoint:

curl --request POST \
  --url https://us.api.jamfcloud.com/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<your_client_ID>' \
  --data-urlencode 'client_secret=<your_client_secret>'

The gateway responds with:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0
}

Make your first API call

Pass the token as a Bearer token in the Authorization header, and the tenant or environment ID in its header.

A platform environment-scoped request to the Devices API:

curl --request GET \
  --url 'https://us.api.jamfcloud.com/devices/v1/devices' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Environment-Id: <your_environment_ID>'

And a tenant-scoped request to the Jamf Pro API, using an integration scoped to that tenant:

curl --request GET \
  --url 'https://us.api.jamfcloud.com/pro/v1/buildings' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Tenant-Id: <your_tenant_ID>'

A 200 OK confirms everything is wired up correctly.

Page through results

Collection endpoints are paginated and accept page, page-size, sort, and an RSQL filter. Response envelopes vary between APIs, so check the reference page for the endpoint you are calling.

See Pagination, sorting, and filtering for the parameters, the RSQL operators, and the envelope shapes.

Where to go next

• Platform API fundamentals: auth, scope levels, regions, permissions, pagination, and errors
• Updating existing Jamf Pro integrations, what to change if you built on the Jamf Pro API or the public beta
• Jamf Pro permissions map, old privilege names to their capability equivalents
• Start building with AI, MCP access to these docs