Add ST V3 docs, update ST-handling recommendation docs

docs/documentation/platform/token.mdx

@@ -3,30 +3,97 @@ title: "Service token"
 description: "Infisical service tokens allows you to programmatically interact with Infisical"
 ---
 
-Service tokens play an integral role in allowing programmatic interactions with an Infisical project, functioning as digital token that open access to specific project resources such as secrets.
+Service tokens are authentication credentials that services can use to access designated endpoints in the Infisical API to manage project resources like secrets.
+Each service token can be provisioned scoped access to select environment(s) and path(s) within them.
 
-When you generate a service token, you can define its access level, not only by specifying the paths and environments it can interact with, but also by determining the level of mutation it can perform, such as read-only, write, or both. 
+## Service Tokens
 
-This level of control not only ensures maximum flexibility but also significantly enhances security as it allows you to define fine grained access to project resources. 
+Infisical currently offers Service Token V3 and Service Token; you can manage both types of tokens in Project Settings > Service Tokens.
 
+### Service Token V3 (Beta)
+
+Service Token V3 (ST V3) is a new and improved authentication method that is in beta. 
+
+<Note>
+  Currently, the Service Token V3 authentication method can only be used with the latest [Node SDK](https://github.com/Infisical/infisical-node) and [Python SDK](https://github.com/Infisical/infisical-python).
+  You can also make an API call with it to create, read, update, or delete secrets.
+
+  We will be releasing compatibility for it with the CLI and K8s operator in the coming month.
+  
+  That said, we recommend using ST V3 whenever possible.
+</Note>
+
+Here's a few pointers to get you acquainted with it:
+
+- When you create a ST V3, you export a `JSON` file containing 3 components: `publicKey`, `privateKey`, and `serviceToken` where
+`serviceToken` is a JWT token prefixed with `proj_token`. The token provides access to the Infisical API and the public-private key
+pairs are to support cryptographic operations for the client whenever E2EE is needed.
+- ST V3 supports IP allowlisting; this means you can restrict the usage of a ST V3 to a specific IP or CIDR range.
+- ST V3 supports provisioning granular `read` or `readWrite` access down to each path.
+- ST V3 supports toggling on/off active states, so you can render a ST V3 inactive without deleting it.
+- ST V3 supports expiration, so, if specified, a token will automatically turn inactive after a period of time.
+- ST V3 tracks most recent usage; it also keeps track of each token's usage count.
+- ST V3 is editable.
+
+### Service Token (Current)
+
+Service Token (ST) is the current widely-used authentication method.
+
+<Note>
+  We recently released ST V3, a revised version of this Service Token, which you can read about above.
+
+  Whenever possible, you should use ST V3 because we will be deprecating ST sometime Q4 2023.
+</Note>
+
+Here's a few pointers to get you acquainted with it:
+
+- When you create a ST, you get a token prefixed with `st`. The part after the last `.` delimiter is a symmetric key; everything
+before it is an access token. When authenticating with the Infisical API, it is important to send in only the access token portion
+of the token.
+- ST supports expiration; it gets deleted automatically upon expiration.
+- ST supports provisioning `read` and/or `write` permissions broadly applied to all accessible environment(s) and path(s).
+- ST is not editable.
 
 ## Creating a service token
 
-To generate the token, head over to your project settings as shown below. On creating a service token you can scope it to a path to limit the access.
+To create a service token, head to Project Settings > Service Tokens as shown below and press **Create token**.
 
 ![token add](../../images/project-token-add.png)
 
-### Service token permissions
-![token add](../../images/service-token-permissions.png)
+Now input any token configuration details such as which environment(s) and path(s) you'd like to provision
+the token access to. Here's some guidance for each field:
 
+- Name: A friendly name for the token.
+- Scopes: The environment(s) and path(s) the token should have access to.
+If using ST V3, you can also indicate whether or not the token should have `read` or `readWrite` access to each path.
+Also, note that Infisical supports [glob patterns](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/) when defining access scopes to path(s).
+- Trusted IPs: The IPs or CIDR ranges that the token can be used from. By default, each token is given the `0.0.0.0/0` entry representing all possible IPv4 addresses.
+- Expiration: The time when this token should be rendered inactive.
 
-Service tokens can be scoped to multiple environments and paths. To add a new permission, choose the environment you want to give access to and then choose the path you'd like to give access to within that environment.
+<Warning>
+  Restricting token usage to specific trusted IPs is a paid feature.
 
-Permissions for paths are powered by [Glob pattern](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/). This means you can create advanced folder permissions with a simple Glob patterns.
+  If you’re using Infisical Cloud, then it is available under the Pro Tier. If you’re self-hosting Infisical, then you should contact team@infisical.com to purchase an enterprise license to use it.
+</Warning>
 
-**Examples of common Glob pattens**
+![token add](../../images/project-token-permissions.png)
 
-<Accordion title="Examples of common Glob pattens">
+In the above screenshot, you can see that we are creating a token token with `read` access to all subfolders at any depth
+of the `/common` path within the development environment of the project; the token expires in 6 months and can be used from any IP address. 
+
+**FAQ**
+
+<AccordionGroup>
+<Accordion title="Why is the Infisical API rejecting my service token?">
+  There are a few reasons for why this might happen:
+  
+  - The service token has expired.
+  - The service token is insufficently permissioned to interact with the secrets in the given environment and path.
+  - You are attempting to access a `/raw` secrets endpoint that requires your project to disable E2EE.
+  - (If using ST V3) The service token has not been activated yet.
+  - (If using ST V3) The service token is being used from an untrusted IP.
+</Accordion>
+<Accordion title="Can you provide examples for using glob patterns?">
   1. `/**`: This pattern matches all folders at any depth in the directory structure. For example, it would match folders like `/folder1/`, `/folder1/subfolder/`, and so on.
 
   2. `/*`: This pattern matches all immediate subfolders in the current directory. It does not match any folders at a deeper level. For example, it would match folders like `/folder1/`, `/folder2/`, but not `/folder1/subfolder/`.
@@ -35,3 +102,4 @@ Permissions for paths are powered by [Glob pattern](https://www.malikbrowne.com/
 
   4. `/folder1/*`: This pattern matches all immediate subfolders within the `/folder1/` directory. It does not match any folders outside of `/folder1/`, nor does it match any subfolders within those immediate subfolders. For example, it would match folders like `/folder1/subfolder1/`, `/folder1/subfolder2/`, but not `/folder2/subfolder/`.
 </Accordion>
+</AccordionGroup>

docs/internals/service-tokens.mdx

@@ -5,10 +5,13 @@ description: "Understanding service tokens and their best practices"
 ​
 Many clients use service tokens to authenticate and read/write secrets from/to Infisical; they can be created in your project settings.
 
+On this page, we discuss Service Token V3, the new and improved authentication method.
+
 ## Anatomy
 
-A service token in Infisical consists of the token itself, a `string`, and a corresponding document in the storage backend containing its 
-properties and metadata.
+A service token in Infisical exports a `JSON` file containing 3 components: `publicKey`, `privateKey`, and `serviceToken` where
+`serviceToken` is a JWT token prefixed with `proj_token`. The token provides access to the Infisical API and the public-private key
+pairs are to support cryptographic operations for the client whenever E2EE is needed.
 
 ### Database model
 
@@ -17,26 +20,46 @@ The storage backend model for a token contains the following information:
 - ID: The token identifier.
 - Expiration: The date at which point the token is invalid.
 - Project: The project that the token is part of.
-- Scopes: The project environments and paths that the token has access to.
-- Encrypted project key: An encrypted copy of the project key.
+- Status: The active/inactive state of a token.
+- Scopes: The project environment(s) and path(s) that the token has access to as well as `read` or `readWrite` permissions for them.
+- Trusted IPs: The specific (IPv4 or IPv6) IPs or CIDR ranges that the token can be used from.
+- Last used: The date at which point the token was last used.
+- Usage count: The number of times that the token has been used.
 
 ### Token
 
-A service token itself consist of two parts used for authentication and decryption, separated by the delimiter `.`. 
+As mentioned before, a service token consists of three components, exported as a `JSON`, used for authentication and cryptographic purposes.
 
-Consider the token `st.abc.def.ghi`. Here, `st.abc.def` can be used to authenticate with the API, by including it in the `Authorization` header under `Bearer st.abc.def`, and retrieve (encrypted) secrets as well as a project key back. Meanwhile, `ghi`, a hex-string, can be used to decrypt the project key used to decrypt the secrets.
+Consider the following `JSON`:
+
+```
+{
+  "publicKey": "...",
+  "privateKey": "...",
+  "serviceToken": "proj_token..."
+}
+```
+
+Here, the `serviceToken` component can be used to authenticate with the API, by including it in the `Authorization` header under `Bearer <serviceToken>` and retrieve (encrypted) secrets as well as a project key back. Meanwhile, the `privateKey` (in the `JSON`), and `publicKey` (returned in the encrypted project key response) can be used to decrypt the project key used to decrypt the secrets.
 
 Note that when using service tokens via select client methods like SDK or CLI, cryptographic operations are abstracted for you that is the token is parsed and encryption/decryption operations are handled. If using service tokens with the REST API and end-to-end encryption enabled, then you will have to handle the encryption/decryption operations yourself.
 ​
 ## Recommendations
 
-### Issuance
+### Permissions
 
-When creating a new service token, it’s important to consider the principle of least privilege(PoLP) when setting its scope and expiration date. For example, if the client using the token only requires access to a staging environment, then you should scope the token to that environment only; you can further scope tokens to path(s) within environment(s) if you happen to use path-based secret storage. Likewise, if the client does not intend to access secrets indefinitely, then you may consider setting a finite lifetime for the token such as 6 months or 1 year from now. Finally, you should consider carefully whether or not your client requires the ability to read and/or write secrets from/to Infisical.
+You should consider the [principle of least privilege(PoLP)](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when setting which environment(s) and path(s)
+should be accessible by a service token; you should also consider whether or not it needs `read` or `readWrite` access.
+
+For example, if the client using the token only requires `read` access to the secrets in the `/config` path of the staging environment, then you should scope the token to the `/config` path of that environment only with `read` permission.
+
+### Status & Expiration
+
+We recommend considering whether or not a service token should be able to access secrets indefinitely or within a finite lifetime such as until 6 months or 1 year from now
 
 ### Network access
 
-We recommend configuring the IP whitelist settings of each project to allow either single IP addresses or CIDR-notated range of addresses to read/write secrets to Infisical. With this feature, you can specify the IP range of your client servers to restrict access to your project in Infisical.
+We recommend configuring the IP allowlist configuration of each service token to restrict its usage to specific IP addresses or CIDR-notated range of addresses.
 
 ### Storage
 
@@ -44,6 +67,6 @@ Since service tokens grant access to your secrets, we recommend storing them sec
 
 ### Rotation
 
-We recommend periodically rotating the service token, even in the absence of compromise. Since service tokens are capable of decrypting project keys used to decrypt secrets, all of which use AES-256-GCM encryption, they should be rotated before approximately 2^32 encryptions have been performed; this follows the guidance set forth by [NIST publication 800-38D](https://csrc.nist.gov/pubs/sp/800/38/d/final).
+We recommend periodically rotating the service token, even in the absence of compromise. Since service tokens are capable of decrypting project keys used to decrypt secrets, they should be rotated before approximately 2^32 encryptions have been performed; this follows the guidance set forth by [NIST publication 800-38D](https://csrc.nist.gov/pubs/sp/800/38/d/final).
 
 Note that Infisical keeps track of the number of times that service tokens are used and will alert you when you have reached 90% of the recommended capacity.