Authentication

The API Control Plane Management API uses Bearer token authentication. Every request must include an Authorization header with a valid token.

curl -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis" \
  -H "Authorization: Bearer <your-token>"

Obtaining a token

There are several ways to obtain a bearer token, depending on your setup and use case.

Option 1: Login with username and password

For non-SSO users or SSO administrators, you can exchange credentials for a token:

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

The bearer token is returned in the Authorization response header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The response body contains the authenticated user's details:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "username": "your-username",
  "displayName": "Your Name",
  "email": "you@example.com",
  "role": "GLOBAL_ADMIN",
  "status": "ACTIVE"
}

Option 2: Personal access tokens

Personal access tokens provide scoped, long-lived access for automation. You can create them via the API:

curl -X POST "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/accessTokens" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Token",
    "validityDays": 90,
    "scopes": [
      "API_READ",
      "API_WRITE",
      "ENVIRONMENT_READ",
      "ENVIRONMENT_WRITE"
    ]
  }'

Response:

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "token": "pat_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "name": "CI/CD Pipeline Token",
  "validUntil": "2026-05-23T00:00:00Z",
  "scopes": ["API_READ", "API_WRITE", "ENVIRONMENT_READ", "ENVIRONMENT_WRITE"]
}

caution

The token value is only returned once at creation time. Store it securely — you cannot retrieve it later.

Available scopes

Scope	Description
API_READ	Read API definitions
API_WRITE	Create, update, delete APIs
ENVIRONMENT_READ	Read environments
ENVIRONMENT_WRITE	Create, update, delete environments
USER_READ	Read user information
USER_WRITE	Manage users
ACCESS_TOKEN_MANAGE	Manage access tokens
APPLICATION_READ	Read applications
APPLICATION_WRITE	Manage applications
PLAN_READ	Read plans
PLAN_WRITE	Manage plans
SUBSCRIPTIONS_READ	Read subscriptions
SUBSCRIPTIONS_WRITE	Manage subscriptions
CONFIGURATION_READ	Read configuration
CONFIGURATION_WRITE	Manage configuration
METRICS_READ	Read metrics
ORGANIZATION_READ	Read organizations
ORGANIZATION_WRITE	Manage organizations
GIT_CREDENTIALS_READ	Read Git credentials
GIT_CREDENTIALS_WRITE	Manage Git credentials
DISCOVERY	API discovery
USER_INVITATION	Invite users
APPROVAL_REQUEST_READ	Read approval requests
APPROVAL_REQUEST_WRITE	Manage approval requests
AUDIT_LOG_READ	Read audit logs
RULE_SETS_READ	Read governance rule sets
RULE_SETS_WRITE	Manage governance rule sets
DEV_PORTAL_READ	Read developer portals
DEV_PORTAL_WRITE	Manage developer portals
WEBHOOKS_READ	Read webhooks
WEBHOOKS_WRITE	Manage webhooks
TERMS_OF_USE_READ	Read terms of use
TERMS_OF_USE_WRITE	Manage terms of use
API_GATEWAY_READ	Read API gateways
API_GATEWAY_WRITE	Manage API gateways
JOBS_READ	Read background jobs
PLAN_ASSIGN_APIS	Assign APIs to plans
READ_GOVERNANCE_DATA	Read governance data
ACCESS_TENANT_DATA	Access tenant-level data
SELF_SERVICE	Self-service operations
CROSS_ORGANIZATION_ACCESS	Access across organizations
SAML_LOGIN	SAML login

Option 3: Boomi Platform API tokens

If you're integrating with the broader Boomi platform, you can use Boomi API tokens:

• Generate tokens in Settings > Account Information and Setup > Boomi Enterprise Platform API Tokens
• For automated calls, use the header format: BOOMI_TOKEN.<username>:<token_value>

curl --user "BOOMI_TOKEN.user@example.com:<token>" \
  -X GET "https://<your-subdomain>.backend.<region>.controlplane.boomi.com/apis"

Option 4: Platform JWT tokens

For short-lived integrations, generate a JWT token from the Boomi platform:

curl --user "username:password" \
  -X GET "https://api.boomi.com/auth/jwt/generate/<accountId>"

warning

JWT tokens expire after 5 minutes. Use them for short-lived operations only.

SSO users

SSO users without Administrator privileges must use personal access tokens or Boomi API tokens. Username/password login is not available for non-admin SSO users.

Managing access tokens

Operation	Method	Path
Create a token	POST	/accessTokens
List your tokens	GET	/accessTokens
Get a token	GET	/accessTokens/{id}
Delete a token	DELETE	/accessTokens/{id}