diff --git a/frontend/src/component/admin/apiToken/ApiTokenForm/ApiTokenForm.tsx b/frontend/src/component/admin/apiToken/ApiTokenForm/ApiTokenForm.tsx index d3018e184b..e3e02d25ec 100644 --- a/frontend/src/component/admin/apiToken/ApiTokenForm/ApiTokenForm.tsx +++ b/frontend/src/component/admin/apiToken/ApiTokenForm/ApiTokenForm.tsx @@ -97,14 +97,14 @@ const ApiTokenForm: React.FC = ({

- Who are you generating the token for? + What would you like to call this token?

setUsername(e.target.value)} - label="Username" + label="Token name" error={errors.username !== undefined} errorText={errors.username} onFocus={() => clearErrors('username')} diff --git a/frontend/src/component/admin/apiToken/CreateApiToken/CreateApiToken.tsx b/frontend/src/component/admin/apiToken/CreateApiToken/CreateApiToken.tsx index 203f1ac1fb..484176ccbb 100644 --- a/frontend/src/component/admin/apiToken/CreateApiToken/CreateApiToken.tsx +++ b/frontend/src/component/admin/apiToken/CreateApiToken/CreateApiToken.tsx @@ -83,7 +83,7 @@ export const CreateApiToken = () => { { + +::: + +The **Unleash front-end API** offers a simplified workflow for connecting a client-side (front-end) applications to Unleash. It provides the exact same API as the [Unleash proxy](../sdks/unleash-proxy.md). The front-end API is a quick and easy way to add Unleash to single-page applications and mobile apps. + + + +Compared to using the Unleash proxy, using the Unleash front-end API has both benefits and drawbacks. The benefits are: + +- **Managing client-side API tokens is easier.** With the Unleash proxy, you need to create and manage client keys manually; with the front-end API, you manage client-side API tokens in the exact same manner as other API tokens. +- **You don't need to configure and run an Unleash proxy.** The front-end API is part of Unleash itself and not an external process. All proxy clients will work exactly the same as they would with the Proxy. + +On the other hand, using the front-end API has the following drawbacks compared to using the proxy: + +- **It can't handle a large number of requests per second.** Because the front-end API is part of Unleash, you can't scale it horizontally the way you can scale the proxy. +- **It sends client details to your Unleash instance.** Unleash only stores these details in its short-term runtime cache, but this can be a privacy issue for some use cases. + +These points make the Unleash front-end API best suited for development purposes and applications that don’t receive a lot of traffic, such as internal dashboards. However, because the API is identical to the Unleash proxy API, you can go from one to the other at any time. As such, you can start out by using the front-end API and switch to using the proxy when you need it. + +## Using the Unleash front-end API + +When using the front-end API in an SDK, there's three things you need to configure. + +### Front-end API tokens + +As a client-side API, you should use a [front-end API token](../reference/api-tokens-and-client-keys.mdx#front-end-api-tokens) to interact with it. Refer to the [how to create API tokens](../user_guide/token.mdx) guide for steps on how to create API tokens. + +### Cross-origin resource sharing (CORS) configuration {#cors} + +You need to allow traffic from your application domains to use the Unleash front-end API with web and hybrid mobile applications. You can update the front-end API CORS settings from the Unleash UI under _admin \> CORS_ or by using the API. + +### API URL + +The client needs to point to the correct API endpoint. The front-end API is available at `/api/frontend`. + + + +### API token + +You can create appropriate token, with type `FRONTEND` on `/admin/api/create-token` page or with a request to `/api/admin/api-tokens`. See our guide on [how to create API tokens](../user_guide/token.mdx) for more details. diff --git a/website/docs/sdks/android-proxy.md b/website/docs/sdks/android-proxy.md index b7202bacb0..5f97f86fa5 100644 --- a/website/docs/sdks/android-proxy.md +++ b/website/docs/sdks/android-proxy.md @@ -5,10 +5,7 @@ title: Android Proxy SDK In this guide we'll explain how to use feature toggles in an Android application using Unleash's [Android Proxy SDK](https://github.com/Unleash/unleash-android-proxy-sdk) and the [Unleash Proxy](https://github.com/Unleash/unleash-proxy). - -:::note -The Android proxy SDK requires the Unleash Proxy to function. You'll need the proxy's URL and a configured proxy secret. Refer to the [proxy documentation](/sdks/unleash-proxy) for how to set it up and [how to configure the proxy secrets](/sdks/unleash-proxy#configuration-variables). -::: +:::note The Android proxy SDK requires the Unleash Proxy or _Unleash v4.16 or later_. Refer to the [Unleash front-end API documentation](/reference/front-end-api.md) guide for simple setup. For large-scale, deployments refer to the [proxy documentation](/sdks/unleash-proxy) for how to set it up and [how to configure the proxy secrets](/sdks/unleash-proxy#configuration-variables). ::: ## How to use the Android Proxy SDK @@ -57,6 +54,7 @@ val myAppContext = UnleashContext.newBuilder() ### Step 4: Configure the Client To create a client, use the `UnleashConfig.newBuilder` method. When building a configuration, you'll need to provide it with: + - `proxyUrl`: the URL your proxy is available at - `clientKey`: the [proxy client key](/sdks/unleash-proxy#configuration-variables) you wish to use (this method was known as `clientSecret` prior to version 0.4.0) - `pollMode`: how you want to load the toggle status diff --git a/website/docs/sdks/go.md b/website/docs/sdks/go.md index 24211de758..2b5bd9f4b9 100644 --- a/website/docs/sdks/go.md +++ b/website/docs/sdks/go.md @@ -52,7 +52,7 @@ To shut down the client (turn off the polling) you can simply call the destroy-m unleash.Close() -### Built in activation strategies {#built-in-activation-strategies} +### Built-in activation strategies {#built-in-activation-strategies} The Go client comes with implementations for the built-in activation strategies provided by unleash. diff --git a/website/docs/sdks/index.md b/website/docs/sdks/index.md index 32519eb9d2..4e4171ee9f 100644 --- a/website/docs/sdks/index.md +++ b/website/docs/sdks/index.md @@ -1,6 +1,6 @@ --- id: index -title: Client SDK overview +title: SDK overview slug: /sdks --- @@ -23,9 +23,9 @@ Server-side clients run on your server and communicate directly with your Unleas - [Rust SDK](https://github.com/unleash/unleash-client-rust) - [.NET SDK](/sdks/dot_net_sdk) -### Front-end SDKs +### Client-side SDKs -For security and performance reasons, the front-end SDKs do not communicate directly with your Unleash instance. Instead, they go via the [Unleash Proxy](unleash-proxy.md). +Client-side SDKs can connect to the [Unleash Proxy](unleash-proxy.md) or to the [Unleash front-end API](../reference/front-end-api.md), but _not_ to the regular Unleash client API. - [Android SDK](/sdks/android_proxy_sdk) - [iOS Proxy SDK](/sdks/proxy-ios) diff --git a/website/docs/sdks/proxy-ios.md b/website/docs/sdks/proxy-ios.md index 96341de427..69b34b6f6a 100644 --- a/website/docs/sdks/proxy-ios.md +++ b/website/docs/sdks/proxy-ios.md @@ -3,7 +3,7 @@ id: proxy-ios title: iOS Proxy SDK --- -In this guide we explain how to use feature toggles in Swift applications via [The Unleash Proxy](./unleash-proxy). You can also checkout the source code for the [iOS Proxy SDK](https://github.com/Unleash/unleash-proxy-client-swift). +In this guide we explain how to use feature toggles in Swift applications via the [Unleash Proxy](./unleash-proxy.md). You can also check out the [source code for the iOS Proxy SDK](https://github.com/Unleash/unleash-proxy-client-swift). ## Introduction {#introduction} diff --git a/website/docs/sdks/proxy-javascript.md b/website/docs/sdks/proxy-javascript.md index 8d9c123270..f18352bcf7 100644 --- a/website/docs/sdks/proxy-javascript.md +++ b/website/docs/sdks/proxy-javascript.md @@ -3,43 +3,57 @@ id: proxy-javascript title: JavaScript Proxy SDK --- -In this guide we explain how to use feature toggles in a Single Page App via [The Unleash Proxy](/sdks/unleash-proxy). You can also checkout the source code for the [JavaScript Proxy SDK](https://github.com/unleash/unleash-proxy-client-js). +This guide shows you how to use feature toggles in a single-page app with the [Unleash Proxy](/sdks/unleash-proxy) and the [Unleash front-end API](../reference/front-end-api). You can also check out the source code for the [JavaScript Proxy SDK](https://github.com/unleash/unleash-proxy-client-js) on GitHub for more details around the SDK. ## Introduction {#introduction} -For single-page apps we have a tiny proxy-client in JavaScript, without any external dependencies, except from browser APIs. This client will store toggles relevant for the current user in local-storage and synchronize with the Unleash Proxy in the background. This means we can bootstrap the toggles for a specific use the next time the user visits the web-page. +The JavaScript proxy client is a tiny Unleash client written in JavaScript without any external dependencies (except from browser APIs). This client stores toggles relevant for the current user in `localStorage` and synchronizes with Unleash (the proxy _or_ the Unleash front-end API) in the background. Because toggles are stored in the user's browser, the client can use them to bootstrap itself the next time the user visits the same web page. > We are looking in to also [supporting react-native](https://github.com/Unleash/unleash/issues/785) with this SDK. Reach out if you want to help us validate the implementation. ## How to use the JavaScript Proxy SDK -**Step 1: Install** +## Step 1: Install ```shell npm2yarn npm install unleash-proxy-client ``` -**Step 2: Initialize the SDK** - -You need to have an Unleash Proxy server running. In addition you will need a proxy-specific `clientKey` in order to connect to the Unleash Proxy. For more on how to set up client keys, [consult the Unleash Proxy docs](unleash-proxy.md#configuration-variables). +## Step 2: Initialize the SDK ```js import { UnleashClient } from 'unleash-proxy-client'; const unleash = new UnleashClient({ url: 'https://eu.unleash-hosted.com/hosted/proxy', - clientKey: 'your-proxy-key', + clientKey: 'your-client-key', appName: 'my-webapp', }); -// Used to set the context fields, shared with the Unleash Proxy +// Use `updateContext` to set Unleash context fields. unleash.updateContext({ userId: '1233' }); // Start the background polling unleash.start(); ``` -**Step 3: Check if feature toggle is enabled** +### Option A: Connecting to the Unleash proxy + +:::tip Prerequisites + +To connect to an Unleash proxy, you need to have an instance of the proxy running. + +::: + +Add the proxy's URL and a [proxy client key](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). The [_configuration_ section of the Unleash proxy docs](unleash-proxy.md#configuration-variables) contain more info on how to configure client keys for your proxy. + +### Option B: Connecting directly to Unleash + +Use the url to your Unleash instance's front-end API (`/api/frontend`) as the `url` parameter. For the `clientKey` parameter, use a `FRONTEND` token generated from your Unleash instance. Refer to the [_how to create API tokens_](/user_guide/api-token) guide for the necessary steps. + +You might also need to set up cross-origin resource sharing (CORS) for your instance. Visit the [CORS section of the front-end API guide](../reference/front-end-api.md#cors) for more information on setting up CORS. + +### Step 3: Check if feature toggle is enabled ```js unleash.isEnabled('proxy.demo'); @@ -54,7 +68,7 @@ if (variant.name === 'blue') { } ``` -**Listen for updates via the EventEmitter** +## Listen for updates via the EventEmitter The client is also an event emitter. This means that your code can subscribe to updates from the client. This is a neat way to update a single page app when toggle state updates. diff --git a/website/docs/sdks/proxy-react.md b/website/docs/sdks/proxy-react.md index ddbed7fa8b..ff2fdcaf51 100644 --- a/website/docs/sdks/proxy-react.md +++ b/website/docs/sdks/proxy-react.md @@ -3,7 +3,7 @@ id: proxy-react title: React Proxy SDK --- -This library is meant to be used with the [unleash-proxy](https://github.com/Unleash/unleash-proxy). The proxy application layer will sit between your unleash instance and your client applications, and provides performance and security benefits. DO NOT TRY to connect this library directly to the unleash instance, as the datasets follow different formats because the proxy only returns evaluated toggle information. +This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../reference/front-end-api). It is _not_ compatible with the regular Unleash client API. For more detailed information, check out the [React Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-react). @@ -23,7 +23,7 @@ The configuration variables are: - **`url`** - Your proxy's URL. + Your proxy's URL or the Unleash front-end API endpoint (`/api/frontend`). - **`clientKey`** @@ -45,7 +45,7 @@ The configuration variables are: import { FlagProvider } from '@unleash/proxy-client-react'; const config = { - url: 'https://HOSTNAME/api/proxy', + url: 'https://PROXY_HOSTNAME/api/proxy', // or https://UNLEASH_HOSTNAME/api/frontend clientKey: 'PROXYKEY', refreshInterval: 15, appName: 'your-app-name', diff --git a/website/docs/sdks/proxy-svelte.md b/website/docs/sdks/proxy-svelte.md index 0321540c10..68db899cd1 100644 --- a/website/docs/sdks/proxy-svelte.md +++ b/website/docs/sdks/proxy-svelte.md @@ -8,7 +8,7 @@ title: Svelte Proxy SDK

-This library is meant to be used with the [unleash-proxy](https://github.com/Unleash/unleash-proxy). The proxy application layer will sit between your unleash instance and your client applications, and provides performance and security benefits. DO NOT TRY to connect this library directly to the unleash instance, as the datasets follow different formats because the proxy only returns evaluated toggle information. +This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../reference/front-end-api). It is _not_ compatible with the regular Unleash client API. For more detailed information, check out the [Svelte Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-svelte). diff --git a/website/docs/sdks/proxy-vue.md b/website/docs/sdks/proxy-vue.md index da8a006668..0eb0fc845a 100644 --- a/website/docs/sdks/proxy-vue.md +++ b/website/docs/sdks/proxy-vue.md @@ -8,7 +8,7 @@ title: Vue Proxy SDK
-This library is meant to be used with the [unleash-proxy](https://github.com/Unleash/unleash-proxy). The proxy application layer will sit between your unleash instance and your client applications, and provides performance and security benefits. DO NOT TRY to connect this library directly to the unleash instance, as the datasets follow different formats because the proxy only returns evaluated toggle information. +This library can be used with the [Unleash Proxy](https://github.com/Unleash/unleash-proxy) or with the [Unleash front-end API](../reference/front-end-api). It is _not_ compatible with the regular Unleash client API. For more detailed information, check out the [Vue Proxy SDK on GitHub](https://github.com/Unleash/proxy-client-vue). diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 9e0a557974..77a2df27eb 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -11,7 +11,7 @@ Looking for how to run the Unleash proxy? Check out the [_How to run the Unleash ::: -A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy concerned way we built The Unleash Proxy +A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy-focused way we built the Unleash proxy. The Unleash Proxy sits between the Unleash API and the application. It provides a simple and super-fast API, as it has all the data it needs available in memory. diff --git a/website/docs/topics/proxy-hosting.mdx b/website/docs/topics/proxy-hosting.mdx index c321a78e3a..d4fe6bed47 100644 --- a/website/docs/topics/proxy-hosting.mdx +++ b/website/docs/topics/proxy-hosting.mdx @@ -64,7 +64,7 @@ You'll need to configure the proxy and the proxy client SDKs. For the proxy, configure: - The Unleash API url. This is your Unleash instance URL followed by "/api". -- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.md) for the steps to create one.) +- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.mdx) for the steps to create one.) - One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../sdks/unleash-proxy#configuration) for more details. For the proxy client SDK, configure: @@ -91,7 +91,7 @@ You'll need to configure the proxy and the proxy client SDKs. For the proxy, configure: - The Unleash API url. This is your Unleash instance URL followed by "/api". -- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.md) for the steps to create one.) +- A [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens). (Refer to [how to create API tokens](../user_guide/token.mdx) for the steps to create one.) - One or more [proxy client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys). Refer to the [configuration section of the proxy document](../sdks/unleash-proxy#configuration) for more details. For the proxy client SDK, configure: diff --git a/website/docs/user_guide/activation-strategies.md b/website/docs/user_guide/activation-strategies.md index a88771b89c..d823b2c166 100644 --- a/website/docs/user_guide/activation-strategies.md +++ b/website/docs/user_guide/activation-strategies.md @@ -59,7 +59,10 @@ This strategy has the following modelling name in the code: ### Custom stickiness (beta) {#custom-stickiness} -:::note This feature is currently in beta and is not yet supported by all our SDKs. Check out the [SDK compatibility table](../sdks/index.md#server-side-sdk-compatibility-table) to see what SDKs support it at the moment. ::: +:::note +This feature is currently in beta and is not yet supported by all our SDKs. Check out the [SDK compatibility table](../sdks/index.md#server-side-sdk-compatibility-table) to see what SDKs support it at the moment. + +::: By enabling the stickiness option on a custom context field you can use the custom context field to group users with the gradual rollout strategy. This will guarantee a consistent behavior for specific values of this context field. diff --git a/website/docs/user_guide/important-concepts.md b/website/docs/user_guide/important-concepts.md index 7e8783df9b..b7103ecf75 100644 --- a/website/docs/user_guide/important-concepts.md +++ b/website/docs/user_guide/important-concepts.md @@ -13,7 +13,7 @@ Activation strategies compound, and every single strategy will be evaluated. If > Unless you add activation strategies on toggle creation, the toggle will be created with the default strategy. The default strategy says that the toggle is either 100% off or 100% on for all users. This means that any other strategies you add will have no effect. If you want to use strategies to control rollout you need to remove the default strategy. -Unleash comes with a set of built in strategies. [But you can also build your own custom strategies.](../advanced/custom_activation_strategy) +Unleash comes with a set of built-in strategies, but you can also build your own [custom strategies](../advanced/custom-activation-strategy.md). [You can read more about activation strategies here.](./activation_strategy) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 92a167d7dd..ab3cd6c66d 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -18,6 +18,7 @@ Have questions that you can't find the answer to in these docs? You can always t ## Documentation structure Our documentation is split into four parts, using the [Diátaxis documentation framework](https://diataxis.fr/): + - [tutorials and introductory material](#tutorials) - [how-to guides](#how-to-guides) - [reference documentation](#reference-documentation) @@ -26,6 +27,7 @@ Our documentation is split into four parts, using the [Diátaxis documentation f ### Tutorials and introductory material {#tutorials} New to Unleash? Not sure where to get started? The tutorials guide you through your first steps with Unleash: + - [Unleash introductory overview](unleash_overview.md) - [Important Unleash concepts](important-concepts.md) - [Quickstart guides](quickstart.md) @@ -35,6 +37,7 @@ New to Unleash? Not sure where to get started? The tutorials guide you through y Our how-to guides show you how to perform a number of common tasks that you'll want to do. Think of them as recipes. They are more advanced than the tutorials and assume you have some working knowledge of Unleash. The guides are organized into the following categories: + - [API how-tos](/how-to/api) - [Feature toggles, strategies, context, and general how-tos](/how-to/misc) - [Users and permissions how-tos](/how-to/users-and-permissions) @@ -45,9 +48,10 @@ The guides are organized into the following categories: The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts. The reference docs are organized into the following topics: + - [Addons](/addons) - [API documentation](/api) -- [Unleash Client SDKs](/sdks) +- [Unleash SDKs](/sdks) - [Deployment and management of Unleash](/deploy) - [Integrations with other systems](/integrations) - [Unleash concepts](/reference/concepts) @@ -58,8 +62,8 @@ The reference docs are organized into the following topics: ## Other resources and communities -💻 The core of Unleash is all open source and [hosted on GitHub](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash "Unleash on GitHub"). +💻 The core of Unleash is all open source and [hosted on GitHub](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash 'Unleash on GitHub'). 💬 If you've got questions or just wanna chat to the team and other Unleash users, come [join our Slack community](https://slack.unleash.run/) -🐦 You can also follow us [on Twitter](https://twitter.com/getunleash "Unleash on Twitter"), [LinkedIn](https://www.linkedin.com/company/getunleash/ "Unleash on LinkedIn"), or [Instagram](https://www.instagram.com/getunleash/ "Unleash on Instagram") for more updates and extra content. +🐦 You can also follow us [on Twitter](https://twitter.com/getunleash 'Unleash on Twitter'), [LinkedIn](https://www.linkedin.com/company/getunleash/ 'Unleash on LinkedIn'), or [Instagram](https://www.instagram.com/getunleash/ 'Unleash on Instagram') for more updates and extra content. diff --git a/website/docs/user_guide/quickstart.md b/website/docs/user_guide/quickstart.md index 63373a9cc2..88fbd838d9 100644 --- a/website/docs/user_guide/quickstart.md +++ b/website/docs/user_guide/quickstart.md @@ -172,7 +172,7 @@ http://CHANGEME/api/admin/features Next, find the navigation, open up the Admin panel and find the API Access tab. Click the "Add new api key" button and create a client key. This key can be used to connect to the instance with our [SDKs](sdks/index.md). -You can find more [information about API keys here](token.md). +You can find more [information about API keys here](token.mdx). Now that you have your API key created, you have what you need to connect to the SDK (NodeJS example): @@ -333,7 +333,7 @@ http://CHANGEME/api/admin/features Find the navigation, open up the Admin panel and find the API Access tab. Click the "Add new api key" button and create a client key. This key can be used to connect to the instance with our [SDKs](sdks/index.md). -You can find more [information about API keys here](token.md). +You can find more [information about API keys here](token.mdx). Now that you have your API key created, you have what you need to connect to the SDK (NodeJS example): diff --git a/website/docs/user_guide/token.md b/website/docs/user_guide/token.md deleted file mode 100644 index 29a24d1f5d..0000000000 --- a/website/docs/user_guide/token.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -id: api-token -title: How to create API Tokens ---- - -In order to connect to Unleash clients will need an API token to grant access. A client SDK will need to token with "client privileges", which allows them to fetch feature toggle configuration and post usage metrics back. - -## Create API Token {#create-api-token} - -### Permissions {#permissions} - -To create an API token you'll need the CREATE_API_TOKEN permission level, at the time of writing (v4.0.0), this level is only set for instance admins. - -Eventually one should be able to customize which users has access to create tokens. - -All users are able to see tokens with CLIENT level access, but only instance admins can see tokens with ADMIN level access. - -### Step-by-step {#step-by-step} - -**1. Select `Advanced` from the top-line menu** -![Admin menu](/img/admin_top-line_menu.png) - -**2. Select `API Access` from the dropdown** - -![Tab Menu](/img/admin_advanced_dropdown.png) - -**3. Select `API ACCESS` from the tab men** -![Tab Menu](/img/admin_tab_menu.png) - -**4. Click `Add new API key` at the top right of the page** -![Tab Menu](/img/admin_new_api_key_button.png) - - -**Client keys** - -4a. If you're configuring an SDK select `Client` in the pop-up. And give the key an identifying name allowing you to recognize it later - -![Api key client](/img/add_new_api_key.png) - -5a. Copy the `Secret` column and add this to your client - -![Api key list](/img/api_key_list.png) - -**Admin operations** - -4a. If you're going to be using the admin interface via CURL you'll need a key with `Admin` rights. Select `Admin` in the `Add new API key` popup. - -Remember to give the key a username allowing you to recognize the key in audit logs later - -5a. Copy the key in the `Secret` column and use it in your authorization header. For curl, that would be `-H "Authorization: "` diff --git a/website/docs/user_guide/token.mdx b/website/docs/user_guide/token.mdx new file mode 100644 index 0000000000..aaa715633b --- /dev/null +++ b/website/docs/user_guide/token.mdx @@ -0,0 +1,38 @@ +--- +id: api-token +title: How to create API Tokens +--- + +import newTokenImage from '/img/admin_create_token_form.png'; + +::: info Permissions + +Creating API tokens requires you to have the `CREATE_API_TOKEN` permission. This means that, as of now, **only instance admins can create API tokens.** + +All users can see tokens with `CLIENT` level access, but only instance admins can see tokens with `ADMIN` level access. + +::: + +Unleash SDKs use API tokens to authenticate to the Unleash API. Unleash supports different types of API tokens, each with different levels of access and privileges. Refer to the [API tokens and client keys](../reference/api-tokens-and-client-keys.mdx) article for complete overview of the different token types. + +## Step 1: Navigate to the API token creation form {#step-1} + +Navigate to the _API access_ page in the admin UI (available at the URL `/admin/api`). Use the navigation menu item "Configure" and select "API access". + +![The admin UI navigation "Configure" submenu with the API access item highlighted.](/img/admin_configure_api.png) + +On the API access page, use the "New API token" button to navigate to the token creation form. + +![The API access page with the "New API token" button highlighted.](/img/admin_new_api_key_button.png) + +## Step 2: Fill in the API token form {#step-2} + +![API token creation form. ](/img/admin_create_token_form.png) + +Fill in the form with the desired values for the token you want to create. Refer to the [API tokens and client keys](../reference/api-tokens-and-client-keys.mdx#token-data) article for a detailed explanation of what all the fields mean. + +## Using API tokens + +When you have created the API token, it will be listed on the API access page. If you have the required permissions to see the token, you can copy it for easy use in your applications. + +![API access token table with a "copy token" button highlighted.](/img/admin_copy_token.png) diff --git a/website/sidebars.js b/website/sidebars.js index 1b7b8f858f..5e656d9da0 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -192,7 +192,7 @@ module.exports = { }, { type: 'category', - label: 'Client SDKs', + label: 'Application SDKs', link: { type: 'doc', id: 'sdks/index' }, items: [ { @@ -289,6 +289,7 @@ module.exports = { 'reference/feature-toggles', 'advanced/feature_toggle_types', 'advanced/toggle_variants', + 'reference/front-end-api', 'reference/playground', 'user_guide/projects', 'user_guide/rbac', diff --git a/website/static/img/add_new_api_key.png b/website/static/img/add_new_api_key.png deleted file mode 100644 index 07850b612f..0000000000 Binary files a/website/static/img/add_new_api_key.png and /dev/null differ diff --git a/website/static/img/admin_advanced_dropdown.png b/website/static/img/admin_advanced_dropdown.png deleted file mode 100644 index 53aab92f26..0000000000 Binary files a/website/static/img/admin_advanced_dropdown.png and /dev/null differ diff --git a/website/static/img/admin_configure_api.png b/website/static/img/admin_configure_api.png new file mode 100644 index 0000000000..c53f13e79f Binary files /dev/null and b/website/static/img/admin_configure_api.png differ diff --git a/website/static/img/admin_copy_token.png b/website/static/img/admin_copy_token.png new file mode 100644 index 0000000000..fe447d151e Binary files /dev/null and b/website/static/img/admin_copy_token.png differ diff --git a/website/static/img/admin_cors.png b/website/static/img/admin_cors.png new file mode 100644 index 0000000000..6f65c70664 Binary files /dev/null and b/website/static/img/admin_cors.png differ diff --git a/website/static/img/admin_create_token_form.png b/website/static/img/admin_create_token_form.png new file mode 100644 index 0000000000..8d3edaaf21 Binary files /dev/null and b/website/static/img/admin_create_token_form.png differ diff --git a/website/static/img/admin_new_api_key_button.png b/website/static/img/admin_new_api_key_button.png index 292b89607a..85e32c06dc 100644 Binary files a/website/static/img/admin_new_api_key_button.png and b/website/static/img/admin_new_api_key_button.png differ diff --git a/website/static/img/admin_tab_menu.png b/website/static/img/admin_tab_menu.png deleted file mode 100644 index a57f32fd82..0000000000 Binary files a/website/static/img/admin_tab_menu.png and /dev/null differ diff --git a/website/static/img/admin_top-line_menu.png b/website/static/img/admin_top-line_menu.png deleted file mode 100644 index 5458a07b9c..0000000000 Binary files a/website/static/img/admin_top-line_menu.png and /dev/null differ diff --git a/website/static/img/api_key_list.png b/website/static/img/api_key_list.png deleted file mode 100644 index 3ae654ed9b..0000000000 Binary files a/website/static/img/api_key_list.png and /dev/null differ