Skip to content

[v4] Dev docs: Add API token documentation #457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Nov 3, 2021
Merged

[v4] Dev docs: Add API token documentation #457

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
36168ab
Add API token documentation
pwizla Oct 25, 2021
e599a26
Delete file(s)
pwizla Oct 25, 2021
afd851a
Add example to full server config
pwizla Oct 25, 2021
4c0193b
Revert changes to REST API
pwizla Oct 27, 2021
6b3e56c
Update how the API token is passed along with the request
pwizla Oct 27, 2021
04a7d1c
Fix typo: unneeded space
pwizla Oct 27, 2021
5d5e951
`apiToken`: camelCase + move to minimal config
pwizla Oct 27, 2021
743d442
Update docs/developer-docs/latest/setup-deployment-guides/configurati…
pwizla Nov 2, 2021
367a036
Update docs/developer-docs/latest/setup-deployment-guides/configurati…
pwizla Nov 2, 2021
ddd4def
Update docs/developer-docs/latest/setup-deployment-guides/configurati…
pwizla Nov 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 0 additions & 99 deletions docs/developer-docs/latest/guides/api-token.md
View file
Open in desktop

This file was deleted.

3 changes: 2 additions & 1 deletion ...oper-docs/latest/setup-deployment-guides/configurations/optional/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,8 @@ Some settings can only be modified through environment variables:
| `NODE_ENV` | String | Type of environment where the app is running | `'development'` |
| `BROWSER` | Boolean | Open the admin panel in the browser after startup | `true` |
| `ENV_PATH` | String | Path to the file that contains your environment variables | `'./.env'` |
| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE` | String | _Optional_<br/><br/>Initialization locale for the app, if the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/developer-docs/latest/plugins/i18n.md#configuration-in-production-environments)) | `'en'` |
| `STRAPI_PLUGIN_I18N_INIT_LOCALE_CODE` <br/><br/>_Optional_| String | Initialization locale for the app, if the [Internationalization (i18n) plugin](/developer-docs/latest/plugins/i18n.md) is installed and enabled on Content-Types (see [Configuration of i18n in production environments](/developer-docs/latest/plugins/i18n.md#configuration-in-production-environments)) | `'en'` |
| `API_TOKEN_SALT`<br/><br/>_Optional_ | String | Salt to use to generate [API tokens](/developer-docs/latest/setup-deployment-guides/configurations/required/server.md#api-tokens) | - |

### Configuration using environment variables

Expand Down
26 changes: 26 additions & 0 deletions ...developer-docs/latest/setup-deployment-guides/configurations/required/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ module.exports = ({ env }) => ({
host: env('HOST', '0.0.0.0'),
port: env.int('PORT', 1337),
admin: {
apiToken: {
salt: env('API_TOKEN_SALT','random_string_used_as_a_salt'),
},
auth: {
secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
},
Expand Down Expand Up @@ -53,6 +56,9 @@ module.exports = ({ env }) => ({
enabled: env.bool('CRON_ENABLED', false),
},
admin: {
apiToken: {
salt: env('API_TOKEN_SALT','random_string_used_as_a_salt'),
},
auth: {
events: {
onConnectionSuccess(e) {
Expand Down Expand Up @@ -100,6 +106,7 @@ module.exports = ({ env }) => ({
| `cron` | Cron configuration (powered by [`node-schedule`](https://github.com/node-schedule/node-schedule)) | Object | |
| `cron.enabled` | Enable or disable CRON tasks to schedule jobs at specific dates. | boolean | `false` |
| `admin` | Admin panel configuration | Object | |
| `admin.apiToken.salt` | Salt used to generate [API tokens](#api-tokens) | String | (A random string<br/>generated<br/>by Strapi) |
| `admin.auth` | Authentication configuration | Object | |
| `admin.auth.secret` | Secret used to encode JWT tokens | string | `undefined` |
| `admin.auth.events` | Record of all the events subscribers registered for the authentication | object | `{}` |
Expand All @@ -115,3 +122,22 @@ module.exports = ({ env }) => ({
| `admin.forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#programmatic-usage) | Object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) |
| `admin.forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) |
| `admin.forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) |

## API tokens

Authentication strategies in Strapi can either be based on the use of the [Users & Permissions plugin](/user-docs/latest/users-roles-permissions/introduction-to-users-roles-permissions.md) or on the built-in [API token]() feature.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@meganelacheny feel free to directly update this PR by adding your link to the user guide docs for API token here :-)


<!-- TODO: add link to API token docs in user guide once written -->

Using API tokens allows executing a request on [REST API](/developer-docs/latest/developer-resources/database-apis-reference/rest-api.md) endpoints as an authenticated user. The API token should be added to the request's `Authorization` header with the following syntax: `bearer your-api-token`.

New API tokens are generated from the admin panel using a salt. This salt is automatically generated by Strapi and stored in `./config/server.js` as `admin.api-tokens.salt`.

The salt can be customized:

- either by updating the string value for `admin.api-tokens.salt` in `./config/server.js`
- or by creating an `API_TOKEN_SALT` [environment variable](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md#environment-variables) in the `.env` file of the project

::: caution
Changing the salt invalidates all the existing API tokens.
:::