Acquia Source uses OAuth 2.0 for API authentication, providing secure access while enabling different authentication flows for various use cases.

API clients¶

An API client represents an application that will be communicating with your Acquia Source site. The CMS provides a default API client for accessing APIs. However, administrators may create additional clients for different purposes, such as separate clients for a mobile app and a Next.js app. 

Each client has:

• A unique client ID
• A client secret for confidential clients
• Authorized scopes that determine what it can access
• Configured grant types that control how it authenticates

Creating a new API client¶

Use the following steps to create a new API client:

1. Access your site.
2. In the left sidebar, click API > API clients.
3. Click Add API client.
4. Enter a name and select the appropriate settings.
5. Save the client to generate credentials.

Grant types¶

OAuth 2.0 supports different grant types for different scenarios. Acquia Source implements following common grant types:

• Authorization code
• Client credentials
• Refresh token

Authorization code¶

This grant type is best for applications where a user is present and needs to authorize access to their account.

The authorization code flow involves:

• Your application redirecting the user to Acquia Source's authorization server
• The user logging in and granting permissions
• Acquia Source redirecting back to your application with a temporary code
• Your application exchanging this code for an access token

Example request:

# Step 1: Redirect user to authorization URL https://your-site.com/oauth/authorize? client_id=YOUR_CLIENT_ID& redirect_uri=YOUR_REDIRECT_URI& response_type=code& scope=content:read user:profile # Step 2: Exchange code for token (server-to-server) POST https://your-site.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=AUTHORIZATION_CODE& client_id=YOUR_CLIENT_ID& client_secret=YOUR_CLIENT_SECRET& redirect_uri=YOUR_REDIRECT_URI

Client credentials¶

This grant type is best for server-to-server communication where no user context is required.

The client credentials flow:

• Uses the client ID and client secret to directly request an access token
• Provides access based on the client's permissions, not a user's
• Is simpler than authorization code but has no user context

Example request:

POST https://your-site.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials& client_id=YOUR_CLIENT_ID& client_secret=YOUR_CLIENT_SECRET& scope=content:read content:write

Refresh token¶

This grant type is used to obtain a new access token when the current one expires.

Refresh tokens:

• Are provided alongside access tokens in some grant types
• Have a longer lifetime than access tokens
• Can be used to get a new access token without requiring user interaction
• Improve security by allowing shorter access token lifetimes

Example request:

POST https://your-site.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token& refresh_token=YOUR_REFRESH_TOKEN& client_id=YOUR_CLIENT_ID& client_secret=YOUR_CLIENT_SECRET

Client settings¶

• Image Styles: Allow or restrict access to image derivatives
• Confidential Client: Whether the client can securely store a secret
• 3rd Party: Whether the client is developed by a third party
• Allowed Scopes: Which API capabilities the client can access
• Redirect URIs: Valid URIs for the authorization code flow