Skip to main content

Authorization

Follow this guide to create a new Akeneo PIM credential that will allow Nexla to authenticate to and exchange data with your Akeneo PIM instance.
akeneo_api_auth.png

Akeneo PIM

Prerequisites​

Akeneo PIM uses OAuth 2.0 to authorize API access. The Akeneo connector in Nexla performs a 3-legged OAuth 2.0 flow against an Akeneo Connected App, which means a PIM administrator authorizes the connector to act on their behalf and Akeneo issues access and refresh tokens that Nexla manages automatically. Before creating a credential in Nexla, register the Akeneo Connected App and collect the Client ID, Client Secret, and the Base URL of the target Akeneo instance.

Determine Your Akeneo Base URL​

Each Akeneo PIM instance is hosted at a specific base URL, and every API call — including the OAuth authorize and token endpoints — is rooted at that URL.

  1. Sign in to your Akeneo PIM instance and copy the host portion of the URL from the browser address bar (for example, https://my-company.cloud.akeneo.com). This is the value to use as the Base URL when creating the Nexla credential.

  2. Customers on Akeneo's public SaaS platform may also use https://api.akeneo.com as the base URL. Self-hosted, Flexibility, or PaaS deployments use the hostname assigned to that instance.

    The same Base URL is used for the OAuth authorization endpoint (/connect/apps/v1/authorize), the token endpoint (/connect/apps/v1/oauth2/token), and every REST API call. Confirm the value with your Akeneo administrator if you are unsure.

Register an Akeneo Connected App​

Akeneo Connected Apps are the recommended way for third-party integrations to access the PIM. A Connected App registration produces the OAuth Client ID and Client Secret that Nexla uses to drive the 3-legged flow.

  1. Sign in to your Akeneo Partner Portal account at partners.akeneo.com and follow the Create an app guide to register a new App. Provide the requested details, including the App name, description, and the Redirect URL.

    • Redirect URL: Set this to the Nexla OAuth callback URL displayed in the Nexla credential overlay when you select the OAuth 2.0 authentication option. The Redirect URL registered with Akeneo must match exactly — including scheme, host, and path — or Akeneo will reject the authorization request.

  2. Configure the Scopes that the App will request. Akeneo defines fine-grained scopes per resource family (for example, read_products, write_products, read_categories, write_categories, read_channel_settings). Select the scopes that match the endpoints the credential will be used with. For a credential that will read and write the full product catalog, the typical set is read_catalog_structure, read_attribute_options, read_categories, read_channel_settings, read_association_types, read_products, write_products, read_product_models, write_product_models, and read_asset_families.

  3. Once the App is registered, Akeneo displays the Client ID and Client Secret on the App settings page. Copy and store both values securely — the Client Secret is shown in full only once at creation time.

    If your Client Secret is lost or exposed, regenerate it from the App settings page in the Akeneo Partner Portal. Regenerating the secret invalidates the previous value, so any existing integrations using the old secret must be updated.

Authorize the App on the Target PIM​

Each Akeneo PIM that the credential connects to must explicitly install and authorize the Connected App. This is performed by an administrator of the target PIM.

  1. As a PIM administrator, sign in to the target Akeneo PIM and open the Connect menu, then select Apps.

  2. Locate the App in the Akeneo App Store catalog (or, for private Apps, use the activation URL provided by the App publisher) and click Activate.

  3. Review the requested scopes and authorizations, and confirm the installation. The App is now installed on this PIM, and any user with permission to manage Apps can complete the OAuth 2.0 consent flow against it.

For complete information about Akeneo Connected Apps, the activation process, and the OAuth 2.0 flow, see the Akeneo Apps authentication and authorization documentation.

Important

The Client Secret grants the ability to obtain access tokens for any PIM that has installed the Connected App. Store it in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed.

Create an Akeneo PIM Credential​

  • To create a new Akeneo PIM credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Akeneo Connection Settings​

  1. Enter the host URL of the target Akeneo PIM instance in the Base URL field (for example, https://my-company.cloud.akeneo.com). This value is used as the root for the OAuth authorization URL, the token URL, and every REST API call made by Nexla. The default value, https://api.akeneo.com, is appropriate for the Akeneo public SaaS instance.

  2. Enter the Client ID issued for your Akeneo Connected App in the Client ID field. The Client ID is shown on the App settings page in the Akeneo Partner Portal.

  3. Enter the Client Secret issued for your Akeneo Connected App in the Client Secret field. The Client Secret is shown in full only once at App creation time and can be regenerated from the App settings page if it is lost.

  4. Enter the space-separated list of OAuth scopes that the credential should request in the Access Scope field. The scopes must be a subset of those configured on the Connected App and should match the endpoints the credential will be used with — for example, read_products write_products read_catalog_structure read_categories read_channel_settings.

    Request only the scopes that are required for the integration. Narrow scopes reduce the impact if a credential is ever compromised, and they align with the principle of least privilege recommended by Akeneo.

  5. Click Authorize to launch the Akeneo PIM consent screen. Sign in to the target Akeneo PIM with an account that has permission to authorize Connected Apps, and approve the requested scopes.

  6. After the consent screen is approved, Akeneo redirects back to Nexla with an authorization code. Nexla automatically exchanges this code for an access token and a refresh token at the ${akeneo_api.base_url}/connect/apps/v1/oauth2/token endpoint, and stores the resulting tokens on the credential. Subsequent API calls reuse the access token, and Nexla automatically refreshes it before expiration using the refresh token.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential. Nexla validates the credential by issuing a GET request to the Akeneo /api/rest/v1/channels endpoint — a successful response confirms that the Base URL, OAuth tokens, and granted scopes are all valid.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.