Application Launcher

Docs

Use Acquia Cloud Platform API v3 (API v3) to programmatically manage your Acquia products. Starting with Multi-Experience Operations (MEO), API v3 centers operations around MEO’s domain entity model. Use these APIs to automate continuous integration and deployment pipelines, manage your multisite portfolios, and integrate internal infrastructure workflows.

Key Capabilities

API 3 updates the management architecture with the following capabilities:

Codebase-centric operations: Map your operations directly to shared codebases rather than single applications.
Granular authorization: Manage secure access control with out-of-the-box support for granular teams and permission models.
Unified architecture: Build predictable integrations using consistent, hierarchical path structures for API routes and event subjects.
Security compliance: Rely on an API gateway architecture that complies with PCI, ISO-SOC2, and FedRAMP security frameworks.

Authentication

All API v3 endpoints require authentication. The API uses JSON Web Token, or JWT, validation. Acquia ID authentication services handle JWT validation securely.

To authenticate programmatic workloads, you must generate API credentials, exchange the credentials for a temporary access token, and include that token in the header of every API v3 request.

Generating API Credentials

Key Capabilities

API 3 updates the management architecture with the following capabilities:

Codebase-centric operations: Map your operations directly to shared codebases rather than single applications.
Granular authorization: Manage secure access control with out-of-the-box support for granular teams and permission models.
Unified architecture: Build predictable integrations using consistent, hierarchical path structures for API routes and event subjects.
Security compliance: Rely on an API gateway architecture that complies with PCI, ISO-SOC2, and FedRAMP security frameworks.

Authentication

All API v3 endpoints require authentication. The API uses JSON Web Token, or JWT, validation. Acquia ID authentication services handle JWT validation securely.

To authenticate programmatic workloads, you must generate API credentials, exchange the credentials for a temporary access token, and include that token in the header of every API v3 request.

Generating API Credentials

Key Capabilities

API 3 updates the management architecture with the following capabilities:

Codebase-centric operations: Map your operations directly to shared codebases rather than single applications.
Granular authorization: Manage secure access control with out-of-the-box support for granular teams and permission models.
Unified architecture: Build predictable integrations using consistent, hierarchical path structures for API routes and event subjects.
Security compliance: Rely on an API gateway architecture that complies with PCI, ISO-SOC2, and FedRAMP security frameworks.

Authentication

All API v3 endpoints require authentication. The API uses JSON Web Token, or JWT, validation. Acquia ID authentication services handle JWT validation securely.

To authenticate programmatic workloads, you must generate API credentials, exchange the credentials for a temporary access token, and include that token in the header of every API v3 request.

Generating API Credentials

Sign in to the Cloud Platform user interface.
Click your user avatar in the upper right corner, and then click Account Settings.
On the Profile page, click API Tokens.
Provide a human-readable label for your API token, and click Create Token.
Cloud Platform displays an API Key and API secret.
Record a copy of your API Key and API secret. For security reasons, you cannot view the secret again after you close the window.

Using the Access Token

To authenticate API v3 requests, you must include the access_token string in the HTTP headers as a Bearer token.

Example Header:Generating an Access Token

After you obtain the credentials, you must exchange the credentials for an access token. Use the standard OAuth 2.0 client credentials flow to exchange the credentials.

Make an HTTP POST request to Acquia token endpoint. You must format the request body as application/x-www-form-urlencoded and pass the API Key and API secret.

Example cURL Request:

curl -X POST "https://accounts.acquia.com/api/auth/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

If the credentials are valid, the endpoint returns a JSON response that contains the temporary access token:

{
  "access_token": "accesstoken",
  "token_type": "Bearer",
  "expires_in": 300
}
Authorization: Bearer <your_access_token>

Token Expiration

For security purposes, the access token expires exactly 300 seconds after Acquia ID generates the token.

Do not generate a new token for every individual API v3 call. Reuse the valid token until the token expires.

After the token expires, API requests fail with a 401 Unauthorized error. You must repeat the POST request to generate a fresh token before you make further API calls.

For more information, refer to Acquia Cloud Platform API (3.0.0).

Frequently asked questions

What is the difference between API v2 and API v3?
API v3 supports the codebase-specific domain model of Multi-Experience Operations (MEO), while API v2 supports legacy Acquia Cloud Enterprise (ACE) and Acquia Cloud Platform (ACP) applications which are environment-based. API v3 extends API v2 capabilities for MEO functions, and both APIs coexist.
Does API v3 replace API v2?
No. API v3 extends API v2 without replacing it. Both APIs continue to operate. API v2 serves Acquia Cloud Enterprise (ACE) and Acquia Cloud Platform (ACP) applications, while API v3 serves Multi-Experience Operations (MEO) applications. Existing API v2 integrations continue to function.
Who should use API v3?
Primary use cases include MEO customers who require API access for automation, and customers who must script CI/CD pipelines for MEO applications.
When should customers migrate to API v3?
Customers must consider API v3 after they acquire MEO environments, must automate MEO operations beyond ACLI capabilities, want to integrate MEO into CI/CD pipelines, or migrate from Site Factory and require API parity.
Do customers need to change their existing integrations?

Click your user avatar in the upper right corner, and then click Account Settings.

On the Profile page, click API Tokens.

Provide a human-readable label for your API token, and click Create Token.

Cloud Platform displays an API Key and API secret.

Record a copy of your API Key and API secret. For security reasons, you cannot view the secret again after you close the window.

Using the Access Token

To authenticate API v3 requests, you must include the access_token string in the HTTP headers as a Bearer token.

Example Header:Generating an Access Token

After you obtain the credentials, you must exchange the credentials for an access token. Use the standard OAuth 2.0 client credentials flow to exchange the credentials.

Make an HTTP POST request to Acquia token endpoint. You must format the request body as application/x-www-form-urlencoded and pass the API Key and API secret.

Example cURL Request:

curl -X POST "https://accounts.acquia.com/api/auth/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

If the credentials are valid, the endpoint returns a JSON response that contains the temporary access token:

{
  "access_token": "accesstoken",
  "token_type": "Bearer",
  "expires_in": 300
}
Authorization: Bearer <your_access_token>

For security purposes, the access token expires exactly 300 seconds after Acquia ID generates the token.

Do not generate a new token for every individual API v3 call. Reuse the valid token until the token expires.

After the token expires, API requests fail with a 401 Unauthorized error. You must repeat the POST request to generate a fresh token before you make further API calls.

For more information, refer to Acquia Cloud Platform API (3.0.0).

Frequently asked questions

What is the difference between API v2 and API v3?
API v3 supports the codebase-specific domain model of Multi-Experience Operations (MEO), while API v2 supports legacy Acquia Cloud Enterprise (ACE) and Acquia Cloud Platform (ACP) applications which are environment-based. API v3 extends API v2 capabilities for MEO functions, and both APIs coexist.
Does API v3 replace API v2?
No. API v3 extends API v2 without replacing it. Both APIs continue to operate. API v2 serves Acquia Cloud Enterprise (ACE) and Acquia Cloud Platform (ACP) applications, while API v3 serves Multi-Experience Operations (MEO) applications. Existing API v2 integrations continue to function.
Who should use API v3?
Primary use cases include MEO customers who require API access for automation, and customers who must script CI/CD pipelines for MEO applications.
When should customers migrate to API v3?
Customers must consider API v3 after they acquire MEO environments, must automate MEO operations beyond ACLI capabilities, want to integrate MEO into CI/CD pipelines, or migrate from Site Factory and require API parity.
Do customers need to change their existing integrations?
- Customers who want direct API access must update URLs and configurations to use API v3 endpoints. For v3-based APIs, customers must switch to newer API commands, such as API v3.
- Site Factory customers must note that API v3 progresses toward parity with Site Factory APIs. Site Factory customers who plan to upgrade to MEO must consult their account management or customer success teams about API parity for specific needs.
How does API v3 affect existing API workflows?
- API v2 workflows require no changes. All existing v2 integrations, scripts, and automations continue to function.
- API v2 serves ACE and ACP, which use an environment-based model. API v3 serves MEO, which uses a codebase-based model. The two APIs operate independently.
- Customers do not face disruptive changes, and migration from API v2 to API v3 remains optional.
Will existing Acquia CLI commands continue to work?
Yes. Existing Acquia CLI commands continue to function, and the old channels remain open.
What are the compliance certifications?
All v3 services are compliant with FedRAMP, ISO, SOC, and PCI.
What is coming in Phase 2?
Future phases will include additional MEO-aware services, parity with Site Factory API capabilities, and Environment settings API.

Customers who want direct API access must update URLs and configurations to use API v3 endpoints. For v3-based APIs, customers must switch to newer API commands, such as API v3.
Site Factory customers must note that API v3 progresses toward parity with Site Factory APIs. Site Factory customers who plan to upgrade to MEO must consult their account management or customer success teams about API parity for specific needs.

How does API v3 affect existing API workflows?

API v2 workflows require no changes. All existing v2 integrations, scripts, and automations continue to function.
API v2 serves ACE and ACP, which use an environment-based model. API v3 serves MEO, which uses a codebase-based model. The two APIs operate independently.
Customers do not face disruptive changes, and migration from API v2 to API v3 remains optional.

Will existing Acquia CLI commands continue to work?

Yes. Existing Acquia CLI commands continue to function, and the old channels remain open.

What are the compliance certifications?

All v3 services are compliant with FedRAMP, ISO, SOC, and PCI.

What is coming in Phase 2?

Future phases will include additional MEO-aware services, parity with Site Factory API capabilities, and Environment settings API.

Did not find what you were looking for?

If this content did not answer your questions, try searching or contacting our support team for further assistance.

Did not find what you were looking for?

If this content did not answer your questions, try searching or contacting our support team for further assistance.