@@ -97,6 +97,8 @@ Currently tokens are generated with the following pattern: `<prefix><random-stri
- Minimum number of routing parts is 1.
- An exception should be raised if no routing part is defined.
- At least one of `c` (Cell ID) or `o` (Organization ID) must be present.
- Valid combinations are: `c` only, `o` only, or both `c` and `o`.
- Maximum number of routing parts is 10.
- An exception should be raised if more than 10 routing parts are defined.
- Minimum size of `<routing-payload>` is 3 bytes (i.e. `o:1`).
@@ -193,11 +195,13 @@ maximum token length (e.g. for secret detection scripts).
### Meaning of fields
Since the payload holds a structured information, each single letter has a
particular meaning. The following fields are always required:
particular meaning. At least one of the following routing fields must be present:
-`c`: Cell ID
-`o`: Organization ID
Both `c` and `o` can be present together, but at least one is required.
The following fields are optional. Each specific tokens can include them if needed:
-`g`: Group ID
@@ -210,6 +214,39 @@ most important information for the specific token. For example, for a user
token, we also include user id. For a project token, we also include the
project id.
#### When to use different routing field combinations
**Routing fields (`c` and `o`):**
At least one of `c` (Cell ID) or `o` (Organization ID) must be present. The
choice depends on the token's scope:
-**Instance tokens** (with `c` only): Use for instance-scoped (cell-scoped)
tokens that are not tied to a specific organization. For example, instance
runner authentication tokens are associated with a cell rather than an
organization. These tokens should specify `c` only, without `o`.
-**Organization tokens** (with `o` or `c` + `o`): Use for tokens that belong
to a specific organization, such as personal access tokens, project access
tokens, and group access tokens. These tokens can include `o` alone (the
routing layer resolves the cell from the organization), or both `c` and `o`
for the most specific routing information.
**Optional fields (`g`, `p`, `u`, `t`):**
It is recommended to include the most specific optional field for each token
type. The Topology Service routes by specificity (preferring `p` over `g` over
`o` over `u` over `c`), so including a more specific field improves routing
accuracy.
This is especially important during the transition period where top-level
groups may move between organizations (e.g., from the default organization).
Including `p` or `g` in the token ensures routing remains correct even if the
organization association changes. For example:
- A **project access token** should include `p` (Project ID).
- A **group access token** should include `g` (Group ID).
- A **personal access token** should include `u` (User ID).
### Adding Classify to Topology Service
It is strongly desired that Classify endpoint of Topology Service could accept routable token payload in full (except for `r`), and make the best routing decision on its own based on available information.
