feat: Add guide for creating and authorizing sessions (#36)

docs/api/applications/applications.mdx

@@ -856,8 +856,8 @@ Returns [an error](/docs/api/errors) if the application failed to delete.
 | Name       | Type         | Description                                                                                                       |
 | ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
 | Private    | `private`    | Used for tokenizing, retrieving, and decrypting data within backend services where the `API key` can be secured   |
-| Public     | `public`     | Used for tokenizing data directly within your mobile or browser application                                       |
-| Management | `management` | Used for managing all aspects of your token infrastructure such as [creating an Application](#create-application) |
+| Public     | `public`     | Used for collecting data within your mobile or browser application                                                |
+| Management | `management` | Used for managing all aspects of your infrastructure such as [creating an Application](#create-application)       |
 
 ### Access Rules
 
@@ -866,9 +866,9 @@ Returns [an error](/docs/api/errors) if the application failed to delete.
 | `description` | _string_ | A description of this Access Rule                                                                                                                                 |
 | `priority`    | _int_    | The priority of the rule, beginning with `1` and higher values having lower precedence                                                                            |
 | `container`   | _string_ | (Optional) The [container](/docs/concepts/what-are-containers) of Tokens this rule is scoped to                                                                   |
-| `conditions`  | _array_  | (Optional) List of [conditions](#applications-access-rules-access-rule-conditions) to be satisfied for the rule to be used. Only apply to sessions                |
-| `transform`   | _string_ | The [transform](#applications-access-rules-access-rule-transforms) to apply to accessed Tokens                                                                    |
-| `permissions` | _array_  | List of [permissions](#permissions-permission-types) to grant on this Access Rule                                                                                 |
+| `conditions`  | _array_  | (Optional) List of [conditions](#access-rule-conditions) to be satisfied for the rule to be used. Only apply to sessions                |
+| `transform`   | _string_ | The [transform](#access-rule-transforms) to apply to accessed Tokens                                                                    |
+| `permissions` | _array_  | List of [permissions](/docs/api/applications/permissions#permission-types) to grant on this Access Rule                                                                                 |
 
 See [Access Rules](/docs/concepts/access-controls#what-are-access-rules) for more information.
 

docs/api/applications/sessions.mdx

@@ -42,7 +42,7 @@ import { BasisTheory } from "@basis-theory/basis-theory-js";
 
 const bt = await new BasisTheory().init("key_N88mVGsp3sCXkykyN2EFED");
 
-const session = await bt.sessions.createSession();
+const session = await bt.sessions.create();
 ```
 
   </TabItem>
@@ -213,9 +213,9 @@ func main() {
 
 | Attribute                          | Required | Type     | Default                   | Description                                                                                                                             |
 | ---------------------------------- | -------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `nonce`                            | true     | _string_ | `null`                    | A one time unique code to authorize the session                                                                                         |
+| `nonce`                            | true     | _string_ | `null`                    | A one-time use code to authorize the session                                                                                            |
 | `permissions`                      | false    | _array_  | `[]`                      | An array of [Permissions](/docs/api/applications/permissions#permission-types) granted to the application tied to the session           |
-| `rules`                            | false    | _array_  | `[]`                      | An array of [Access Rules](#access-rules) granted to the application tied to the session                                                |
+| `rules`                            | false    | _array_  | `[]`                      | An array of [Access Rules](/docs/api/applications#access-rules) granted to the application tied to the session                          |
 | `expires_at`                       | false    | _string_ | `null`                    | ISO8601 compatible DateTime in which the session will be deleted. By default it is 3 minutes from the session creation date             |
 
 Either `permissions` or `rules` is required to be non-empty when authorizing a Session.
@@ -229,5 +229,5 @@ Returns no payload. Returns [an error](/docs/api/errors) if there were validatio
 | Attribute                          | Type     | Description                                                                                           |
 | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
 | `session_key`                      | _string_ | The Session API key which should be used for authenticating against Basis Theory API endpoints        |
-| `nonce`                            | _string_ | A one time unique code to authorize the session                                                       |
+| `nonce`                            | _string_ | A one-time use code to authorize the session                                                          |
 | `expires_at`                       | _date_   | Expiring date of the Session in ISO 8601 format. Defaults to 3 minutes after the creation date        |

docs/concepts/access-controls.mdx

@@ -69,6 +69,12 @@ A short description of the Application describing its intended use, for example
 
 - **Management**: Used with scripts or the [Basis Theory Terraform Provider](https://registry.terraform.io/providers/Basis-Theory/basistheory) to manage your Tenant's settings and services (Applications, Reactors, Proxy, etc) without logging into our Portal.
 
+<Alert>
+  There are some <a href="#why-use-sessions">inherent risks</a> associated with embedding a public API key within a public-facing frontend application.
+  Take the time to understand these <a href="#why-use-sessions">risks</a> and consider using <a href="#what-are-sessions">sessions</a> within
+  your frontend applications to mitigate these risks.
+</Alert>
+
 ### Access Controls
 
 An Application is granted access to your Tenant's resources in one of two ways: by granting the Application a set of
@@ -163,6 +169,49 @@ This enables engineers to write scripts or to use IaC (Infrastructure as Code) t
 
 ![Applications IaC](/img/concepts/applications_iac.png)
 
+## What are Sessions?
+
+Sessions provide an alternative mechanism to grant temporary elevated access to your public applications.
+
+Generally speaking, sessions are created by and issued to a public application (within your frontend) and authorized by a private application (within your backend).
+Sessions can be authorized to only access specific tokens or containers, and to perform a limited set of operations on those tokens.
+You can learn more about how to create and authorize sessions in the guide [Access Data Using Sessions](/docs/guides/govern/sessions) or
+continue reading below to learn more about when to consider using sessions.
+
+### Why Use Sessions?
+
+Sessions can help you achieve improved security by limiting the access granted to a public application and its API key.
+Since public API keys are used within frontend applications, they can potentially be accessed by untrusted parties
+who inspect or decompile your web or mobile application source code, or by inspecting network traffic in their browser or device. Because of these risks,
+Basis Theory only allows public applications to be granted permission to create or update tokens to support [collecting data](/docs/guides/collect/),
+and never to read or use tokens.
+
+However, even granting access to create or update tokens introduces risk, as unauthorized third parties could
+potentially gain access to your public API key and perform malicious actions:
+
+- Tokens could be created within your tenant by unauthorized third parties, increasing your MAT count and potentially incurring charges
+- If a token ID were exposed or guessed, that token could be updated by an unauthorized actor without your consent
+
+Using sessions within a public application fully mitigates these risks and offers the following benefits over a public API key-only approach:
+
+- **Prevent Anonymous Use**: Since sessions are authorized by a private application in a backend service that you own, you are able to authenticate all requests for a session.
+- **User-Specific Access Controls**: You can apply your own custom authorization logic to limit access to only the tokens that should be accessible by each user.
+- **Ability to Read or Use Tokens**: Sessions can be authorized to perform any token operation, not only creating or updating tokens.
+- **Limited Lifetime**: Sessions are created just-in-time and are intended to be short-lived - by default, sessions expire after 3 minutes.
+
+### Use Cases for Sessions
+
+Sessions enable you to fully mitigate many of the [risks](#why-use-sessions) associated with exposing public API keys, while also enabling use cases
+beyond collecting data within your frontend applications.
+
+Sessions are a good fit for the following use cases:
+
+- Revealing tokens in a front end application in plaintext (see [reveal sensitive data with Elements](/docs/sdks/web/javascript#reveal-sensitive-data))
+- Calling the proxy or reactors from your frontend application
+- Restricting the access granted to public API keys to prevent unauthorized use
+  - Only allow tokens to be created by authenticated users in your system
+  - Only allow tokens to be updated by authenticated and authorized users in your system
+
 ## What are Access Rules?
 
 Access Rules are the building blocks for constructing fine-grained access control policies for an Application.
@@ -204,7 +253,7 @@ then reading tokens in the `/pci/high/` container will return masked data, and r
 ### Conditions
 
 Conditions allow specifying more specific restrictions for the access rule to be matched, such as scoping them to a
-specific token. For example, having a condition with attribute `ID`, operator `EQUALS` and value `<tokenId>`, will
+specific token. For example, having a condition with attribute `id`, operator `equals` and value `<tokenId>`, will
 allow the application to only access the token with the given `<tokenId>` ID.
 
 Conditions are mutually exclusive with Container and are currently only available for Sessions.

docs/guides/govern/audit-data-access.mdx

@@ -1,4 +1,4 @@
-import { Alert, Alerts } from "@site/src/components/shared/Alert";
+import { Alert } from "@site/src/components/shared/Alert";
 import { AuthButtons } from "@site/src/components/docs/AuthButtons";
 
 # Audit Data Access
@@ -93,4 +93,4 @@ Using [Audit Logs](/docs/api/logs) and [log filters](/docs/api/logs#query-parame
 ## Learn More
 
 - [Control Data Access](/docs/guides/govern/control-data-access)
-- [Access Controls](/docs/concepts/access-controls)
+- [Access Controls](/docs/concepts/access-controls)

docs/guides/govern/control-data-access.mdx

@@ -1,4 +1,4 @@
-import { Alert, Alerts } from "@site/src/components/shared/Alert";
+import { Alert } from "@site/src/components/shared/Alert";
 import { AuthButtons } from "@site/src/components/docs/AuthButtons";
 
 # Control Data Access
@@ -9,7 +9,7 @@ Key concepts in this guide:
 
 - [Applications](/docs/api/applications)
 - [Access Controls](/docs/concepts/access-controls)
-- [Token Containers?](/docs/concepts/what-are-containers)
+- [Token Containers](/docs/concepts/what-are-containers)
 
 ## Getting Started
 

docs/guides/govern/index.mdx

@@ -39,4 +39,13 @@ Controlling data access and being able to audit that access is critical to meet
   >
     Audit data access and usage across your environment.
   </Card>
-</Card.TwoColumnLayout>
+
+  <Card
+    column
+    img={<Govern />}
+    href="/docs/guides/govern/sessions"
+    heading="Access Data Using Sessions"
+  >
+    Grant temporary access to your data using sessions.
+  </Card>
+</Card.TwoColumnLayout>