Skip to content

Commit 2bdcabe

Browse files
Bassel17pwizla
Bassel17
and
pwizla
authored
Viewable API tokens in the admin panel (#2484)
* doc: update api tokens, viewable tokens * Update docusaurus/docs/cms/features/api-tokens.md * Refine docs --------- Co-authored-by: Pierre Wizla <[email protected]> Co-authored-by: Pierre Wizla <[email protected]>
1 parent a0424db commit 2bdcabe

File tree

2 files changed

+69
-22
lines changed

2 files changed

+69
-22
lines changed

‎docusaurus/docs/cms/configurations/admin-panel.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ The `/config/admin` file can include the following parameters:
2424
| Parameter | Description | Type | Default |
2525
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------|
2626
| `apiToken.salt` | Salt used to generate [API tokens](/cms/features/api-tokens) | string | Random string |
27+
| `apiToken.secrets.encryptionKey` | Encryption key used to set [API tokens visibility](/cms/features/api-tokens#ensuring-api-tokens-are-visible-in-the-admin-panel) in the admin panel | string | Random string |
2728
| `auditLogs.enabled` | Enable or disable the [Audit Logs](/cms/features/audit-logs) feature | boolean | `true` |
2829
| `auditLogs.retentionDays` | How long [Audit Logs](/cms/features/audit-logs) are kept, in days.<br /><br />_The behavior differs for self-hosted vs. Strapi Cloud customers, see the note under the table._ | integer | 90 |
2930
| `auth` | Authentication configuration | object | - |
@@ -140,6 +141,9 @@ export default ({ env }) => ({
140141
module.exports = ({ env }) => ({
141142
apiToken: {
142143
salt: env('API_TOKEN_SALT', 'someRandomLongString'),
144+
secrets: {
145+
encryptionKey: env('ENCRYPTION_KEY'),
146+
},
143147
},
144148
auditLogs: { // only accessible with an Enterprise plan
145149
enabled: env.bool('AUDIT_LOGS_ENABLED', true),
@@ -195,6 +199,9 @@ module.exports = ({ env }) => ({
195199
export default ({ env }) => ({
196200
apiToken: {
197201
salt: env('API_TOKEN_SALT', 'someRandomLongString'),
202+
secrets: {
203+
encryptionKey: env('ENCRYPTION_KEY'),
204+
},
198205
},
199206
auditLogs: { // only accessible with an Enterprise plan
200207
enabled: env.bool('AUDIT_LOGS_ENABLED', true),

‎docusaurus/docs/cms/features/api-tokens.md‎

Lines changed: 62 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ description: Learn how you can use API tokens to manage end-users authentication
44
sidebar_position: 2
55
toc_max_heading_level: 5
66
tags:
7-
- api tokens
8-
- admin panel
9-
- authentication
10-
- users & permissions
11-
- features
7+
- api tokens
8+
- admin panel
9+
- authentication
10+
- users & permissions
11+
- features
1212
---
1313

1414
# API Tokens
@@ -34,8 +34,8 @@ API tokens allow users to authenticate REST and GraphQL API queries (see [APIs i
3434
</IdentityCard>
3535

3636
<ThemedImage
37-
alt="API tokens"
38-
sources={{
37+
alt="API tokens"
38+
sources={{
3939
light: '/img/assets/settings/settings_pregen-api-tokens.png',
4040
dark: '/img/assets/settings/settings_pregen-api-tokens_DARK.png',
4141
}}
@@ -47,42 +47,44 @@ Most configuration options for API tokens are available in the admin panel, and
4747

4848
### Admin panel settings
4949

50-
**Path to configure the feature:** <Icon name="gear-six" /> *Settings > Global settings > API Tokens*
50+
**Path to configure the feature:** <Icon name="gear-six" /> _Settings > Global settings > API Tokens_
5151

52-
The *API Tokens* interface displays a table listing all of the created API tokens. More specifically, it displays each API token's name, description, date of creation, and date of last use.
52+
The _API Tokens_ interface displays a table listing all of the created API tokens. More specifically, it displays each API token's name, description, date of creation, and date of last use.
5353

5454
From there, you have the possibility to:
5555

5656
- click on the <Icon name="pencil-simple" /> to edit an API token's name, description, type, duration or [regenerate the token](#regenerating-an-api-token).
5757
- click on the <Icon name="trash" /> to delete an API token.
5858

5959
:::note
60-
Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one. Since tokens can be only seen once after creation, you have to [regenerate](#regenerating-an-api-token) them before using them.
60+
Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one. Since tokens can be only seen once without encryption configured, you may want to [regenerate](#regenerating-an-api-token) them after setting up an encryption key to make them permanently viewable.
6161
:::
6262

6363
#### Creating a new API token
6464

6565
1. Click on the **Create new API Token** button.
6666
2. In the API token edition interface, configure the new API token:
67-
| Setting name | Instructions |
68-
| -------------- | ------------------------------------------------------------------------ |
69-
| Name | Write the name of the API token. |
70-
| Description | (optional) Write a description for the API token. |
71-
| Token duration | Choose a token duration: *7 days*, *30 days*, *90 days*, or *Unlimited*. |
72-
| Token type | Choose a token type: *Read-only*, *Full access*, or *Custom*. |
73-
3. (optional) For the *Custom* token type, define specific permissions for your API endpoints by clicking on the content-type name and using checkboxes to enable or disable permissions.
67+
| Setting name | Instructions |
68+
| -------------- | ------------------------------------------------------------------------ |
69+
| Name | Write the name of the API token. |
70+
| Description | (optional) Write a description for the API token. |
71+
| Token duration | Choose a token duration: _7 days_, _30 days_, _90 days_, or _Unlimited_. |
72+
| Token type | Choose a token type: _Read-only_, _Full access_, or _Custom_. |
73+
3. (optional) For the _Custom_ token type, define specific permissions for your API endpoints by clicking on the content-type name and using checkboxes to enable or disable permissions.
7474
4. Click on the **Save** button. The new API token will be displayed at the top of the interface, along with a copy button <Icon name="copy" />.
7575

7676
<ThemedImage
77-
alt="Custom API token"
78-
sources={{
77+
alt="Custom API token"
78+
sources={{
7979
light: '/img/assets/settings/settings_api-token-custom.png',
8080
dark: '/img/assets/settings/settings_api-token-custom_DARK.png',
8181
}}
8282
/>
8383

84-
:::caution
85-
For security reasons, API tokens are only shown right after they have been created. When refreshing the page or navigating elsewhere in the admin panel, the newly created API token will be hidden and will not be displayed again.
84+
:::info Viewable tokens
85+
If an encryption key is configured in your Strapi project (`admin.secrets.encryptionKey`), the newly created and regenerated API tokens will be **viewable at any time** in the admin panel.
86+
87+
If no encryption key is set, tokens will only be viewable **once**, immediately after creation or regeneration.
8688
:::
8789

8890
#### Regenerating an API token
@@ -98,13 +100,51 @@ New API tokens are generated using a salt. This salt is automatically generated
98100

99101
The salt can be customized:
100102

101-
- either by updating the string value for `apiToken.salt` in `./config/admin.js` (see [admin panel configuration documentation](/cms/configurations/admin-panel))
103+
- either by updating the string value for `apiToken.salt` in [your `/config/admin` file](/cms/configurations/admin-panel)
102104
- or by creating an `API_TOKEN_SALT` [environment variable](/cms/configurations/environment#strapi) in the `.env` file of the project
103105

104106
:::caution
105107
Changing the salt invalidates all the existing API tokens.
106108
:::
107109

110+
#### Ensuring API tokens are visible in the admin panel
111+
112+
To allow persistent visibility of API tokens in the admin panel, an encryption key must be provided in [your `/config/admin` file](/cms/configurations/admin-panel) under `apiToken.secrets.encryptionKey`:
113+
114+
<Tabs groupId="js-ts">
115+
<TabItem label="JavaScript" value="js">
116+
117+
```js title="/config/admin.js"
118+
module.exports = ({ env }) => ({
119+
// other config parameters
120+
apiToken: {
121+
secrets: {
122+
encryptionKey: env('ENCRYPTION_KEY'),
123+
},
124+
}
125+
});
126+
```
127+
128+
</TabItem>
129+
130+
<TabItem label="TypeScript" value="ts">
131+
132+
```js title="/config/admin.ts"
133+
export default ({ env }) => ({
134+
// other config parameters
135+
apiToken: {
136+
secrets: {
137+
encryptionKey: env('ENCRYPTION_KEY'),
138+
},
139+
}
140+
});
141+
```
142+
143+
</TabItem>
144+
</Tabs>
145+
146+
This key is used to encrypt and decrypt token values. Without this key, tokens remain usable, but will not be viewable after initial display. New Strapi projects will have this key automatically generated.
147+
108148
## Usage
109149

110150
Using API tokens allows executing a request on [REST API](/cms/api/rest) or [GraphQL API](/cms/api/graphql) endpoints as an authenticated user.

0 commit comments

Comments
 (0)