diff --git a/docs/develop/authentication/streaming-token.md b/docs/develop/authentication/streaming-token.md index d185513f..e00039b9 100644 --- a/docs/develop/authentication/streaming-token.md +++ b/docs/develop/authentication/streaming-token.md @@ -1,16 +1,20 @@ # Streaming token -A streaming token is a type of bearer token that can be used to authenticate your client library (Quix Streams) to access functionality necessary for streaming actions. Think of streaming tokens as a token you use to access Quix, but with limited scope. +A streaming token is a type of bearer token that can be used to authenticate your client library (Quix Streams) to access functionality necessary for streaming actions. Think of a streaming token as a token you use to access Quix, but with limited scope. -Each environment comes with one of these tokens, limited in use for that specific environment. +!!! important -## How to find + Each Quix environment comes with one of these tokens, limited in use to that specific environment. For example, if you obtain a streaming token from your production environment, the the streaming token is scoped to only authenticate connection of the client to the production environment. + +As streaming tokens are scoped to a specific environment, it means you can specify a topic name, even if that same topic name is used across multiple environments. This is because the topic ID is automatically used for you, based on the streaming token used. For example, if you had a topic called `f1-data` in production and development environments, you could simply use the topic name of `f1-data` in your code, regardless of the environment you're connecting to. In production, the topic ID might be `orgname-projectname-prod-f1-data`, and in development it might be `orgname-projectname-dev-f1-data`, however, the correct topic ID is automatically used by Quix Streams, as the environment is identified in the token, and therefore the correct prefix to the topic name can be generated. + +## How to get a streaming token You can access these tokens by logging into Quix and clicking on `Settings` in the main left-hand navigation. Select your environment, and then click on `APIs and tokens` and then click on `Streaming Tokens`. If you are looking for a bearer token to access the Quix APIs, such as the Portal API, you can select `Personal Access Tokens`. These are custom JWTs. -## How to use +## How to use a streaming token The streaming token is primarily used to authenticate the [Quix Streams client library](https://quix.io/docs/quix-streams/introduction.html). @@ -20,7 +24,7 @@ When using Quix Streams in Quix Cloud, you no longer need to provide all broker Streaming tokens do not have an expiration date. Treat them as you would a password. If you think they’re exposed, rotate them. -## Rotating +## Rotating your token If you suspect your streaming token may have been exposed, best practice is to rotate it. Within the `Streaming token` dialog, click `rotate them` to display the `Rotating streaming tokens` dialog. Two tokens are then displayed. @@ -35,3 +39,7 @@ You have two main options regarding how you rotate: !!! note Only users with Admin role can rotate. + +## See also + +* [Testing multiple environments](../../manage/testing-environments.md) diff --git a/docs/manage/testing-environments.md b/docs/manage/testing-environments.md new file mode 100644 index 00000000..e569c426 --- /dev/null +++ b/docs/manage/testing-environments.md @@ -0,0 +1,51 @@ +# Testing multiple environments + +Sometimes you want a Quix Streams client to initially use one environment, and then configure it to work with another environment. This is sometimes done to test different environments. This can be achieved by simply changing the streaming token used to authenticate your Quix Streams client. + +In Quix Streams a [streaming token](../develop/authentication/streaming-token.md) is used to authenticate Quix Streams with a specific environment. + +!!! tip + + Quix Cloud automatically injects the streaming token inside the Quix Streams configuration using the `Quix__Sdk__Token` environment variable. Note that the streaming token is also known as an SDK token. + + +## Token is scoped to an environment + +Each streaming token is scoped to one environment - this is the environment in which it is obtained. For example, if you obtain the token from your production environment, then it is scoped to work only with that environment. + + +## Using `.env` and the Quix CLI to select an environment + +If you are working locally you may to point to different environments while you are developing your pipeline. + +You can use the Quix CLI to select the environment you want to connect to, and it will manage your `.env` file configuration for you. + +First you use the `quix use` command to select your environment. Then you run `quix local variables export` inside your application folder which generates the `.env` file to configure the streaming token of the selected environment. + +!!! tip + + This command is run automatically by your IDE if you have configured it previously with the command `quix local init`, for example, `quix local init --vscode`. + +You might want to connect to a local broker for testing and development. Use the `quix context broker set` command to set up your local broker configuration. + +You can then switch from a local broker to the Quix Cloud environment using `quix context broker toggle`. + +!!! tip + + Use `quix context current` to check which environment or local broker you are pointing to. + +## Passing token to the Application object + +Alternatively, you can specify the SDK token directly in your client code. This is done when creating the `Application` object in your Quix Streams client, for example: + +``` python +Application(quix_sdk_token="sdk-49..a5") +``` + +This value overrides the `Quix__Sdk__Token` environment variable, which is set for you automatically when running code in Quix Cloud, or any local environment you may have set through using Quix CLI or environment files or variables. + +## Topic names across multiple environments + +Topics have a topic name and a topic ID. The topic name is a short textual name which may be the same across multiple environments. The topic ID uniquely identifies the topic across all organizations, projects, and environments. + +As streaming tokens are scoped to a specific environment, it means you can specify a topic name, even if that same topic name is used across multiple environments. This is because the topic ID is automatically used for you, based on the streaming token used. For example, if you had a topic called `f1-data` in production and development environments, you could simply use the topic name of `f1-data` in your code, regardless of the environment you're connecting to. In production, the topic ID might be `orgname-projectname-prod-f1-data`, and in development it might be `orgname-projectname-dev-f1-data`, however, the correct topic ID is automatically used by Quix Streams, as the environment is identified in the token, and therefore the correct prefix to the topic name can be generated. diff --git a/mkdocs.yml b/mkdocs.yml index 23877ef3..56f730e5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,6 +104,7 @@ nav: - 'MLOps': 'manage/MLOps.md' - 'Using replay service': 'manage/replay.md' - 'Testing using Quix data store': 'manage/testing-data-store.md' + - 'Testing multiple environments': 'manage/testing-environments.md' - 'Query API': - 'Overview': 'apis/query-api/overview.md' - 'Setup': 'apis/query-api/setup.md'