Skip to content

Commit 757c54a

Browse files
samokisssamokiss
authored
Merge pull request #676 from akeneo/API-1895
feat(API-1895): create 'how to get app token' page
2 parents d531cdb + 29d0afb commit 757c54a

11 files changed

+212
-35
lines changed

‎content/apps/apps-how-to-get-your-app-token.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# How to get your App token
2+
3+
Implement the required parts of the App activation process and receive an App access token for querying your PIM API.
4+
5+
<table class="tag-container">
6+
<tr>
7+
<td>Use case:</td>
8+
<td>
9+
<button aria-pressed="false" class="tag-selectable">
10+
<div class="tag-color tag-color-light-blue"></div>
11+
<div class="tag-label">App Workflow</div>
12+
</button>
13+
</td>
14+
</tr>
15+
</table>
16+
17+
## What you will learn
18+
In this tutorial, we provide a guide on how to implement the required parts of your App for the activation process based on OAuth 2.0 with Authorization Code.
19+
At the end of this tutorial, your App will receive an Access Token and will be able to call the REST API of a PXM Studio.
20+
21+
::: warning
22+
Examples in this tutorial use languages without any framework or library and, consequently, don't follow all the recommended best practices.
23+
We strongly encourage you to adapt those examples with the framework or library of your choice.
24+
:::
25+
26+
::: tips
27+
If you prefer to start with a fonctionnal App (in PHP), have a look [here](/apps/app-developer-tools.html)
28+
:::
29+
30+
## Step 1: Expose your activation and callback URLs
31+
32+
First, your application must expose an **activation URL**.
33+
34+
In our example, we won't do additional steps (like authentification), so we will launch the Authorization Request immediately in this Activation URL.
35+
36+
!!!include(content/apps/create-app/activate-php.md)!!!
37+
!!!include(content/apps/create-app/activate-nodejs.md)!!!
38+
!!!include(content/apps/create-app/activate-python.md)!!!
39+
!!!include(content/apps/create-app/activate-java.md)!!!
40+
41+
Then, your application must expose a **callback URL**.
42+
43+
!!!include(content/apps/create-app/callback-php.md)!!!
44+
!!!include(content/apps/create-app/callback-nodejs.md)!!!
45+
!!!include(content/apps/create-app/callback-python.md)!!!
46+
!!!include(content/apps/create-app/callback-java.md)!!!
47+
48+
49+
::: info
50+
You can find more information about the authorization process and code challenge in the following documentation.
51+
- [OAuth Authorization and authentication](/apps/authentication-and-authorization.html#)
52+
:::
53+
54+
## Step 2: Get a public URL for your in development App
55+
56+
::: info
57+
if you use a local version of PIM, skip this step
58+
:::
59+
60+
Before proceeding to step 4 create a test App in your developer sandbox, you will need valid URLs to your App. This can be easily resolved with a tunnel to your localhost.
61+
62+
There are several ways to create a tunnel to your localhost such as **localhost.run** or **ngrok**. We will use [localhost.run](https://localhost.run/) for its free and easy setup.
63+
64+
### Initiate localhost tunnel
65+
66+
Initiate localhost tunnel using the following command:
67+
68+
```shell
69+
70+
ssh -R 80:localhost:8080 localhost.run
71+
```
72+
73+
The command above assumes that your local App is available on port 8080 but you can specify any port you want.
74+
75+
76+
### Extract URL from the output
77+
78+
If everything goes well the command will output your public URL for your local app:
79+
80+
```shell
81+
82+
46672a93dd64.lhrtunnel.link tunneled with tls termination, https://46672a93dd64.lhrtunnel.link
83+
```
84+
85+
Your local app is now available at `https://46672a93dd64.lhrtunnel.link`. You may now use it for your development.
86+
87+
## Step 3: Get your test app credentials
88+
89+
To get credentials for your app, you need to create a test app on your developer sandbox.
90+
91+
First of all, go to `Connect`, then `App Store`
92+
93+
### Permissions
94+
95+
If you see `Create a test App` skip to [Connect app](https://www.notion.so/Guided-tutorial-How-to-get-your-app-token-022acb1113c1413faefaec3c8f3585a5), else please enable the `developer mode`.
96+
![Create a test app button](../img/apps/create-a-test-app-button.png)
97+
98+
To do so, you need to:
99+
1. Go to `System`, then `Roles`
100+
2. Choose the role you use for your user
101+
3. In the `Permissions` tab, scroll down and search for the `Developer mode` submenu
102+
4. Select `Manage test apps`
103+
5. Don't forget to save your modifications
104+
105+
### Connect app
106+
107+
To create a test App:
108+
1. On the top right corner, click on `Create a test App`
109+
2. Fill in all the required information
110+
![Test_app_creation_credentials](../img/apps/test-app-creation-info.png)
111+
3. Then click on `Create`
112+
4. Copy/paste credentials in your app configuration file
113+
![Test_app_creation_credentials](../img/apps/test-app-creation-credentials.png)
114+
5. And click on `Done`
115+
6. Your test App appears on the App Store page
116+
117+
118+
## Step 4: Connect your test App and access its settings
119+
120+
![Test app on the App Store](../img/apps/marketplace-with-test-app.png)
121+
122+
Connecting a test App is like connecting a published App.
123+
124+
1. Launch your APP
125+
2. Click on `Connect`
126+
3. Your App opens in a new tab of your browser
127+
4. Launch the connection process from your App
128+
5. Follow all the activation process steps, then `Confirm`
129+
6. Your test App is now connected with Akeneo PIM! 🔗
130+
131+
Now that your App is connected, you can enjoy all the available App features from the Akeneo PXM Studio UI and test that your App works well.
132+
133+
To access the settings of your connected App on Akeneo PIM, please go to `Connected Apps`, then click on `Manage App`.
134+
You can also open your App from Akeneo PIM UI, to do so, click on `Open app`.
135+
136+
![Connected test app on Apps](../img/apps/connected-test-app.png)
137+
138+
::: info
139+
To know more about the step-by-step activation process, please read our article:
140+
[How to connect an App?](https://help.akeneo.com/pim/serenity/articles/how-to-connect-my-pim-with-apps.html#how-to-connect-an-app)
141+
:::
142+
143+
## Step 5: Use your access token to call the API
144+
145+
At the end of this process, you receive the following response with an `access_token`:
146+
147+
```json
148+
149+
{
150+
"access_token": "Y2YyYjM1ZjMyMmZlZmE5Yzg0OTNiYjRjZTJjNjk0ZTUxYTE0NWI5Zm",
151+
"token_type": "bearer",
152+
"scope": "read_products write_products"
153+
}
154+
```
155+
156+
You can use this token to call the Akeneo PIM REST API.
157+
158+
<div class="block-next-steps">
159+
<img src="../img/illustrations/illus--Attribute.svg" width="140px">
160+
<div class="block-next-steps-column">
161+
<div class="block-next-steps-title">Next Steps</div>
162+
<div class="block-next-steps-text">Now that you collected your categories, we advise you to follow</div>
163+
<div>
164+
<ul>
165+
<li><a href="https://api.akeneo.com/apps/overview.html">Learn more about Apps</a></li>
166+
<li><a href="https://api-staging.akeneo.com/api-reference-index.html">Explore the REST API reference</a></li>
167+
</ul>
168+
</div>
169+
</div>
170+
</div>

‎content/apps/create-app/activate-php.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22

33
// Let's create an `activate.php` file
44

5-
const OAUTH_CLIENT_ID = '<CLIENT_ID>';
6-
const OAUTH_SCOPES = 'read_products write_products';
5+
$oauthClientId = '<CLIENT_ID>';
6+
$getAuthorizationUrl = '%s/connect/apps/v1/authorize?%s';
7+
$scopes = ['read_products', 'write_products', 'delete_products'];
78

89
session_start();
910

@@ -23,14 +24,13 @@ $_SESSION['pim_url'] = $pimUrl;
2324
// https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
2425
$authorizeUrlParams = http_build_query([
2526
'response_type' => 'code',
26-
'client_id' => OAUTH_CLIENT_ID,
27-
'scope' => OAUTH_SCOPES,
27+
'client_id' => $oauthClientId,
28+
'scope' => implode(' ', $scopes),
2829
'state' => $state,
2930
]);
3031

3132
// Build the url for the Authorization Request using the PIM URL
32-
$authorizeUrl = $pimUrl . '/connect/apps/v1/authorize?' . $authorizeUrlParams;
33-
34-
// Redirect the user to the Authorization URL
35-
header('Location: ' . $authorizeUrl);
33+
$url = sprintf($getAuthorizationUrl, $pimUrl, $authorizeUrlParams);
34+
header('Location: '.$url);
35+
exit;
3636
```

‎content/apps/create-app/callback-php.md

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
```php [callback:PHP]
22

3-
// Let's create a `callback.php` file:
3+
// Let's create a `callback.php` file
44

5-
const OAUTH_CLIENT_ID = '<CLIENT_ID>';
6-
const OAUTH_CLIENT_SECRET = '<CLIENT_SECRET>';
5+
require_once __DIR__ . '/../vendor/autoload.php';
6+
7+
$oauthClientId = '<CLIENT_ID>';
8+
$oauthClientSecret = '<CLIENT_SECRET>';
9+
$generateTokenUrl = '/connect/apps/v1/oauth2/token';
710

811
session_start();
912

@@ -24,25 +27,29 @@ if (empty($pimUrl)) {
2427
exit('No PIM url in session');
2528
}
2629

30+
// Generate code for token request
2731
$codeIdentifier = bin2hex(random_bytes(30));
28-
$codeChallenge = hash('sha256', $codeIdentifier . OAUTH_CLIENT_SECRET);
32+
$codeChallenge = hash('sha256', $codeIdentifier . $oauthClientSecret);
2933

30-
$accessTokenUrl = $pimUrl . '/connect/apps/v1/oauth2/token';
34+
// Build form data to post
3135
$accessTokenRequestPayload = [
32-
'client_id' => OAUTH_CLIENT_ID,
36+
'client_id' => $oauthClientId,
3337
'code_identifier' => $codeIdentifier,
3438
'code_challenge' => $codeChallenge,
3539
'code' => $authorizationCode,
3640
'grant_type' => 'authorization_code',
3741
];
3842

39-
// Do a POST request on the token endpoint
40-
$ch = curl_init();
41-
curl_setopt($ch, CURLOPT_URL, $accessTokenUrl);
42-
curl_setopt($ch, CURLOPT_POST, true);
43-
curl_setopt($ch, CURLOPT_POSTFIELDS, $accessTokenRequestPayload);
44-
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
45-
$response = json_decode(curl_exec($ch), true);
43+
// If you haven't set your client yet, please install Guzzle by following the official documentation:
44+
// https://docs.guzzlephp.org/en/stable/overview.html#installation
45+
$client = new GuzzleHttp\Client(['base_uri' => $pimUrl]);
46+
47+
// Make an authenticated call to the API
48+
$accessTokenUrl = $pimUrl . $generateTokenUrl;
49+
$response = $client->post($accessTokenUrl, ['form_params' => $accessTokenRequestPayload]);
50+
51+
// Convert json response to array
52+
$contents = json_decode($response->getBody()->getContents(), true);
4653

47-
echo $response['access_token'];
54+
var_export($contents);
4855
```

‎content/apps/how-to-retrieve-pim-structure.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Retrieve the PIM structure through a channel resource. This is usually the requi
3636
<img src="../img/illustrations/illus--Attributegroup.svg" width="110px">
3737
<div class="block-requirements-steps">
3838
<ul>
39-
<li>Step 1. <a href="apps-getting-started.html" target="_blank" rel="noopener noreferrer">Get your App token tutorial</a></li>
39+
<li>Step 1. <a href="apps-how-to-get-your-app-token.html" target="_blank" rel="noopener noreferrer">Get your App token tutorial</a></li>
4040
</ul>
4141
</div>
4242
</div>
@@ -61,7 +61,7 @@ If you haven't set your client yet, please:
6161
- Install Guzzle by following the <a href="https://docs.guzzlephp.org/en/stable/overview.html#installation" target="_blank" rel="noopener noreferrer">official documentation</a>
6262
- Set your client for querying Akeneo API as follows:
6363

64-
```php
64+
```php [activate:PHP]
6565

6666
$pimUrl = 'https://url-of-your-pim.com';
6767
$appToken = 'your_app_token'; // Token provided during oAuth steps

‎content/apps/apps-getting-started.md renamed to ‎content/apps/old/apps-getting-started.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Feel free to contribute with languages we're not experts at.
2626

2727
## Requirements
2828
- You have your [App developer starter kit](/apps/overview.html#app-developer-starter-kit)
29-
- You understand [what's an Akeneo App](/apps/apps-getting-started.html#whats-an-akeneo-app) and [how they fit into Akeneo PXM Studio](/apps/apps-getting-started.html#how-apps-fit-into-akeneo-pxm-studio)
29+
- You understand [what's an Akeneo App](/apps/overview.html#whats-an-akeneo-app) and [how they fit into Akeneo PXM Studio](/apps/overview.html#how-apps-fit-into-akeneo-pxm-studio)
3030

3131
## Step 1: Expose your activation and callback URLs
3232

@@ -85,7 +85,7 @@ Your local app is now available at `https://46672a93dd64.lhrtunnel.link`. You ma
8585

8686
To get credentials for your app, you need to create a test app on your developer sandbox.
8787

88-
![Create a test app button](../img/apps/create-a-test-app-button.png)
88+
![Create a test app button](../../img/apps/create-a-test-app-button.png)
8989

9090
To create a test App:
9191
1. Go to `Connect`, then `App Store`
@@ -96,7 +96,7 @@ To create a test App:
9696
6. And click on `Done`
9797
7. Your test App appears on the App Store page
9898

99-
![Test app creation](../img/apps/test-app-creation.png)
99+
![Test app creation](../../img/apps/test-app-creation.png)
100100

101101

102102
If you don't see the `Create a test App` button, please enable the `developer mode`.
@@ -110,7 +110,7 @@ To do so, you need to:
110110

111111
## Step 4: Connect your test App and access its settings
112112

113-
![Test app on the App Store](../img/apps/marketplace-with-test-app.png)
113+
![Test app on the App Store](../../img/apps/marketplace-with-test-app.png)
114114

115115
Connecting a test App is like connecting a published App.
116116

@@ -125,7 +125,7 @@ Now that your App is connected, you can enjoy all the available App features fro
125125
To access the settings of your connected App on Akeneo PIM, please go to `Connected Apps`, then click on `Manage App`.
126126
You can also open your App from Akeneo PIM UI, to do so, click on `Open app`.
127127

128-
![Connected test app on Apps](../img/apps/connected-test-app.png)
128+
![Connected test app on Apps](../../img/apps/connected-test-app.png)
129129

130130
::: info
131131
To know more about the step-by-step activation process, please read our article:

‎content/apps/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,6 @@ Your app is good to go?
7777

7878
## Next steps
7979

80-
- Learn more about how to [create an app](/apps/apps-getting-started.html#create-an-app)
80+
- Learn more about how to [create an app](/apps/apps-how-to-get-your-app-token.html#how-to-get-app-token)
8181
- Read our documentation about [authorization and authentication](/apps/authentication-and-authorization.html)
8282
- Learn how to use [catalogs](/apps/catalogs.html) to retrieve product data

‎content/img/apps/test-app-creation-credentials.png

58.4 KB
Loading

‎content/img/apps/test-app-creation-info.png

57.1 KB
Loading

‎src/api-reference/reference.handlebars

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@
154154
<code>Authorization</code>
155155
<a href="#" data-placement="top" data-toggle="tooltip" title="Required header"> <i class="fa fa-asterisk fa-danger"></i> </a>
156156
{{#if x-app-token}}
157-
<small>&bull; Equal to 'Bearer xxx', 'xxx' being the App authentication token, see <a href="/apps/apps-getting-started.html" target="_blank">documentation for getting an app token</a></small>
157+
<small>&bull; Equal to 'Bearer xxx', 'xxx' being the App authentication token, see <a href="/apps/apps-how-to-get-your-app-token.html" target="_blank">documentation for getting an app token</a></small>
158158
{{else}}
159159
<small>&bull; Equal to 'Bearer xxx', `xxx` being the authentication token, see <a href="/documentation/authentication.html">Authentication</a> section</small>
160160
{{/if}}

‎src/index.handlebars

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<div class="hidden-xs hidden-sm col-md-6 col-lg-5">
1010
<h1 class="emphasis">Build Apps to ease the connection with Akeneo PIM</h1>
1111
<p>Follow our step-by-step guide to create an app and use OAuth 2.0</p>
12-
<a class="btn btn-primary" href="/apps/apps-getting-started.html">Build an App</a>
12+
<a class="btn btn-primary" href="/apps/apps-how-to-get-your-app-token.html">Build an App</a>
1313
</div>
1414
<div class="hidden-xs hidden-sm col-md-6 col-lg-7">
1515
<img class="img-responsive img-banner" src="img/illustrations/illus--main-banner-apps.svg"></img>
@@ -19,7 +19,7 @@
1919
<div class="hidden-xs hidden-md hidden-lg col-sm-6">
2020
<h1 class="emphasis">Build Apps to ease the connection with Akeneo PIM</h1>
2121
<p>Follow our step-by-step guide to create an app and use OAuth 2.0</p>
22-
<a class="btn btn-primary" href="/apps/apps-getting-started.html">Build an App</a>
22+
<a class="btn btn-primary" href="/apps/apps-how-to-get-your-app-token.html">How to get App token</a>
2323
</div>
2424
<div class="hidden-xs hidden-md hidden-lg col-sm-6">
2525
<img class="img-responsive img-banner" src="img/illustrations/illus--main-banner-apps.svg"></img>
@@ -32,7 +32,7 @@
3232
<div class="hidden-sm hidden-md hidden-lg col-xs-12">
3333
<h1 class="emphasis">Build Apps to ease the connection with Akeneo PIM</h1>
3434
<p>Follow our step-by-step guide to create an app and use OAuth 2.0</p>
35-
<a class="btn btn-primary" href="/apps/apps-getting-started.html">Build an App</a>
35+
<a class="btn btn-primary" href="/apps/apps-how-to-get-your-app-token.html">How to get App token</a>
3636
</div>
3737
</div>
3838
</div>

0 commit comments

Comments
 (0)