feat: add docs for namespaced tokens

authentication/methods.mdx

@@ -58,6 +58,24 @@ The bootstrap token can also be configured to have an expiration date by setting
 
 See the [Configuration: Method Token](/configuration/overview#authentication-methods-token) documentation for more details.
 
+### Token Expiration
+
+Tokens can be created with an optional expiration date. This can be used to ensure that a token is only valid for a short period of time before automatically expiring. Expired tokens will be automatically be deleted by Flipt. The interval and grace period for this cleanup process can be configured via the `token.cleanup.interval` and `token.cleanup.grace_period` values in the configuration.
+
+### Namespaced Tokens
+
+Tokens can be created with an optional namespace to allow for more granular control over access to resources. Namespaces allow for grouping resources such as flags, segments, etc. To learn more about namespaces, see the [Concepts: Namespaces](/concepts#namespaces) documentation.
+
+Namespaced tokens are useful for the scenario when you want to limit the privileges of an integration such as a CI/CD pipeline or internal service.
+
+<Info>
+It's important to note that namespaced tokens offer limited access to the Flipt API, as only API requests that can be scoped to a namespace are supported.
+</Info>
+
+For example, the `/api/v1/namespaces/{namespace}/flags` endpoint supports a `namespace` parameter, therefore a namespaced token can be used to access this endpoint. However, the `/auth/v1/tokens` endpoint is not associated with a single `namespace`, so a namespaced token cannot be used to access this endpoint.
+
+This also means that namespaced tokens themselves cannot be used to create additional tokens. Tokens must be created using a non-namespaced (default) token.
+
 ## OpenID Connect
 
 [OpenID Connect](https://openid.net/connect/) (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

authentication/using-tokens.mdx

@@ -57,7 +57,7 @@ def doRequest():
 ### 2. `Cookie` Header
 
 <Warning>
-  Please enable [CSRF](/configuration/authentication#session) prevention in your
+  It's important to enable [CSRF](/configuration/authentication#session) prevention in your
   Flipt configuration when using a "session compatible" authentication method
   and `Cookie` based authentication in the browser.
 </Warning>

reference/overview.mdx

@@ -10,6 +10,23 @@ The Flipt REST API can also be used with any language that can make HTTP request
 
 The latest version of the REST API is fully documented using the [OpenAPI v3 specification](https://github.com/flipt-io/flipt-openapi).
 
+## SDKs
+
+We're adding new SDKs all the time. To see the latest list of SDKs, head to the [REST SDKs](/integration/rest) documentation
+
+## Authentication
+
+<Info>
+Flipt authentication is **disabled** (not required) by default.
+
+Head to the [Configuration: Authentication](/configuration#authentication) section to enable it.
+
+</Info>
+
+Once enabled, the Flipt REST API uses tokens for authentication. The token is passed in the `Authorization` header of the request as a `Bearer` token.
+
+For more information on how to create a token, see the [Authentication](/authentication) documentation.
+
 ## Backward Compatibility
 
 We take great care to ensure that the Flipt REST API is backward compatible. This means that you can safely upgrade to a newer version of Flipt without having to change your API calls.
@@ -33,34 +50,3 @@ Version [v1.20.0](https://github.com/flipt-io/flipt/releases/tag/v1.20.0) of Fli
 All previous endpoints without the `/namespaces` prefix still work as before (i.e.: `/api/v1/flags`), they simply resolve to using the **default** namespace.
 
 See the [Concepts: Namespaces](/concepts#namespaces) section for more information.
-
-## SDKs
-
-Official REST client SDKs exist for the following languages:
-
-- [Go](https://pkg.go.dev/go.flipt.io/flipt/sdk/go)
-- [Node.js/TypeScript](https://github.com/flipt-io/flipt-node)
-- [Java](https://github.com/flipt-io/flipt-java)
-- [Rust](https://github.com/flipt-io/flipt-rust)
-- [Python](https://github.com/flipt-io/flipt-python)
-
-<Note>
-We're working on more REST API SDKs and would love to hear from you if you're
-interested in helping out or have a request for an SDK in a specific language.
-
-Please reach out to us in our [Discord server](https://www.flipt.io/discord).
-
-</Note>
-
-## Authentication
-
-<Info>
-Flipt authentication is **disabled** (not required) by default.
-
-Head to the [Configuration: Authentication](/configuration#authentication) section to enable it.
-
-</Info>
-
-Once enabled, the Flipt REST API uses tokens for authentication. The token is passed in the `Authorization` header of the request as a `Bearer` token.
-
-For more information on how to create a token, see the [Authentication](/authentication) documentation.